Jupyter 대화형 문서에 대한 재고
오늘 나는 그 이후로 많이 발전하지 않은 화제를 탐구하고 싶다. 나는 믿는다
업그레이드가 필요할 수 있습니다.Jupyter 세션에서 대화식 문서에 액세스하고 해당 문서가 될 수 있는 것은 무엇입니까?마지막으로, 모험을 좋아한다면, 나는 현재의 원형에 연결될 것이다.
현재 사용자에 대한 제한
현재 IPython과 Jupyter에 관한 문서는 몇 가지 형식이 있지만 대부분은 같은 제한이 있다.도움말을 구하는 전형적인 방식은 ?
조작원을 사용하는 것이다.사용하는 프런트엔드에 따라 현재 객체에 대한 정보를 표시하는 호출기 또는 패널이 제공됩니다.
현재 객체(서명, 파일, 하위/수퍼 클래스) 및 객체의 원래 DocString에 대한 정보를 표시할 수 있습니다.
스크롤할 수 있지만 터미널이든 노트북이든 마찬가지다.
NumPy 웹 사이트의 동일한 문서와 비교합니다.
왼쪽은 NumPy가 액세스한 문서the NumPy website입니다.이를 렌더링 문서라고 합니다.Jupyter Lab, IPython 또는 일반 Python REPL에서 얻은 정확한 정보에 대해 도움말 문서를 호출합니다. 보통 identifier?
또는 help(identifier)
를 통해 접근하기 때문입니다.
제공된 문서와 비교하여 도움말 문서는 다음과 같습니다.
저자에 대한 제한
Jupyter와 IPython은 문서 표시에 대한 제한으로 인해 작성자가 일반적으로 문서 기능에 포함된다고 생각합니다.
읽기 편리하도록 docstrings의 문법은 보통 간단합니다. 이것은 첫 번째 버전입니다
일반적인 환경 설정:
You can use ``np.einsum('i->', a)`` ...
긴 형식으로 렌더링을 볼 때 참조를 링크로 바꿉니다.
도움말 문서로 표시될 때 읽기 어려운 문서:
You can use :py:func:`np.einsum('i->', a) <numpy.einsum>` ...
이것 또한 고급 분야에서 어떤 문법을 사용하는지에 대한 장기적인 토론을 초래했다. 예를 들어 Sympy's docstrings의 공식이다.
많은 항목이 동적 문서 열을 실현해야 한다.예를 들어 함수나 클래스 사용**kwargs
이 전달하는 모든 매개 변수(예를 들어 matplotlib 소스 코드_kwdoc
를 검색하거나 보기pandas.DataFrame
실현)를 포함한다.
이로 인해 작가와 공헌자들은 전면적인 문서를 정확하게 유지하고 제공하기 어렵다.
나는 이것이 도서관 관리자가 문서를 작성하는 방식에 발생하는 모든 부작용을 완전히 예측할 수 있을지 확실하지 않다.그러나 나는 그곳을 돕기 위해 좋은 기회와 도구가 있다고 믿는다.예를 들어, 를 참조하여 자주 발생하는 NumPyDoc 형식 오류와 오류를 자동으로 다시 포맷하고 수정하려고 합니다.
타자 오류입니다. 하지만 이것은 미래 게시물의 주제입니다.
웨린
바위와 단단한 곳 사이에 갇히다
Sphinx와 관련 항목은 위탁 관리 HTML 문서를 제공하는 데 매우 뛰어나지만, 그것들의 광범위한 사용으로 인해 상호작용 문서를 더욱 사용하기 어렵다.
가능
하지만 대부분의 스핑크스 인형 기능은 완전한 프로젝트를 구축할 때만 작동할 수 있고 적당한 배치와 확장이 있으며 대량의 계산이 필요할 수 있다.이로 인해 현지에서 사자 인형을 운행하는 것은 현실에 맞지 않게 되었다.
위탁 관리 사이트는 일반적으로 로컬에 설치된 라이브러리 버전을 반영하지 못할 수 있으므로 플랫폼이나 특정 버전의 기능을 중심으로 자세히 링크하고 사용하지 않으며 서술해야 한다.
docstring을 렌더링할 때 Sphinx를 동적으로 실행합니다.
이건 해결할 수 있어요.
지난 몇 달 동안, 나는 IPython (그리고 Jupyter) 이 문서를 어떻게 표시하는지 다시 쓰려고 노력해 왔다.터미널(IPython)과 브라우저 환경(notebook, JupyterLab, Spyder)에서 정상적으로 작동하고 적당한 렌더링 효과가 있어 현재 대부분의 명령을 이해할 수 있다.새로운 컨텐츠에 대한 사용자 정의를 수행할 수 있습니다.
이상은 scipy.polynomial.lagfit
의 (단말기) 문서입니다. 단일 점프를 정확하게 이해하고 이미 알고 있는 파라미터를 참고하십시오. 이것은 `n`
가 정확하지 않습니다. 왜냐하면 이중 점프를 가지고 있어야 하기 때문입니다.terminal에서도 수학의 표현은 이와 같다는 것을 주의하세요.
기술적으로 말하자면 이것은 문서 문자열이 RST로 작성되었는지Markdown으로 작성되었는지에 관심이 없다.뒷부분이 필요하지만그러나 나는 일부 관리자들이 Markdown을 기꺼이 사용할 것이라고 믿는다. 이것은 더 많은 사용자들이 익숙한 문법이다.
터미널에서 내비게이션을 지원하며 링크에 있는enter 키를 누르거나 누르면 목표 페이지에 들어갈 수 있습니다.위의gif에서 코드 예시 중의 많은 태그도 자동으로 유형 추정을 하고 이를 클릭하여 해당하는 페이지를 탐색할 수 있습니다.
Jedi
그림은 터미널에서 내연이 아닌 단추로 바뀌어 첫 번째 뷰어에서 열 수 있도록 포함됩니다. (위 캡처된 Open with quicklook
참조.
미래.
특히 다음과 같은 몇 가지 기능을 개발하고 있습니다.
You can use ``np.einsum('i->', a)`` ...
You can use :py:func:`np.einsum('i->', a) <numpy.einsum>` ...
Sphinx와 관련 항목은 위탁 관리 HTML 문서를 제공하는 데 매우 뛰어나지만, 그것들의 광범위한 사용으로 인해 상호작용 문서를 더욱 사용하기 어렵다.
가능 하지만 대부분의 스핑크스 인형 기능은 완전한 프로젝트를 구축할 때만 작동할 수 있고 적당한 배치와 확장이 있으며 대량의 계산이 필요할 수 있다.이로 인해 현지에서 사자 인형을 운행하는 것은 현실에 맞지 않게 되었다.
위탁 관리 사이트는 일반적으로 로컬에 설치된 라이브러리 버전을 반영하지 못할 수 있으므로 플랫폼이나 특정 버전의 기능을 중심으로 자세히 링크하고 사용하지 않으며 서술해야 한다.
docstring을 렌더링할 때 Sphinx를 동적으로 실행합니다.
이건 해결할 수 있어요.
지난 몇 달 동안, 나는 IPython (그리고 Jupyter) 이 문서를 어떻게 표시하는지 다시 쓰려고 노력해 왔다.터미널(IPython)과 브라우저 환경(notebook, JupyterLab, Spyder)에서 정상적으로 작동하고 적당한 렌더링 효과가 있어 현재 대부분의 명령을 이해할 수 있다.새로운 컨텐츠에 대한 사용자 정의를 수행할 수 있습니다.
이상은 scipy.polynomial.lagfit
의 (단말기) 문서입니다. 단일 점프를 정확하게 이해하고 이미 알고 있는 파라미터를 참고하십시오. 이것은 `n`
가 정확하지 않습니다. 왜냐하면 이중 점프를 가지고 있어야 하기 때문입니다.terminal에서도 수학의 표현은 이와 같다는 것을 주의하세요.
기술적으로 말하자면 이것은 문서 문자열이 RST로 작성되었는지Markdown으로 작성되었는지에 관심이 없다.뒷부분이 필요하지만그러나 나는 일부 관리자들이 Markdown을 기꺼이 사용할 것이라고 믿는다. 이것은 더 많은 사용자들이 익숙한 문법이다.
터미널에서 내비게이션을 지원하며 링크에 있는enter 키를 누르거나 누르면 목표 페이지에 들어갈 수 있습니다.위의gif에서 코드 예시 중의 많은 태그도 자동으로 유형 추정을 하고 이를 클릭하여 해당하는 페이지를 탐색할 수 있습니다.
Jedi
그림은 터미널에서 내연이 아닌 단추로 바뀌어 첫 번째 뷰어에서 열 수 있도록 포함됩니다. (위 캡처된 Open with quicklook
참조.
미래.
특히 다음과 같은 몇 가지 기능을 개발하고 있습니다.
특히 다음과 같은 몇 가지 기능을 개발하고 있습니다.
예를 들어,
numpy.linspace
페이지에서 볼 수 있습니다.참조 또는 샘플 섹션에서 사용
numpy.linspace
(위의 그림 참조).지금, 그것은 내가 원하는 것처럼 빠르고 효율적이지 않습니까? 비록 Sphinx를 실행하는 것보다 빠르지만, 약간의 사전 처리가 필요합니다.그것은 많은 곳에서 붕괴되었다.Scipy, NumPy, xarray, IPython, scikit 이미지 등 대부분의 문서를 보여 줍니다.
Jupyter의 문서를 사용할 때 어떤 기능이 부족한지 생각해 보고 알려 주십시오.Jupyter 내부에서 문서를 볼 때 Sphinx에 좋은 보충이 되기를 바랍니다.
현재, 나는 이미 의 신청을 제출하여, 그 중 일부 업무 자금을 IPython에 투입하려고 시도하고 있으며, 만약 당신의 도서관에 기부하거나 비슷한 물건을 원한다면 언제든지 연락하십시오.
저장소Letter of intent to CZI EOSS 4를 찾을 수 있습니다. 아직 알파의 초기 단계에 있습니다.그것은 여전히 매우 불안정하다. 내 입맛에 맞는 하드코딩 값이 너무 많아서, 약간의 수식이 있어야만 생산에 사용할 수 있다.저는 현재 단말기 렌더링에 주력하고 있습니다. Jupyter 노트북이나 JupyterLab 확장을 환영합니다.따라서 모험을 좋아하고 최첨단(심지어 최첨단)부터 일하는 것을 좋아한다면 언제든지 시도하고 질문/요청을 하세요.
그것은 더 좋은 기록(쌍관어)이 필요하다. 나는 종이사초 자체로 종이사초를 기록하고 싶다.하지만 좀 더 성숙해져야 한다.
계속해서 더 많은 뉴스를 주목해 주십시오. 저는 후속 게시물에서 그것이 어떻게 작동하는지 더 상세하게 설명하고 프로젝트의 장점 (단점) 을 토론할 것입니다.
Reference
이 문제에 관하여(Jupyter 대화형 문서에 대한 재고), 우리는 이곳에서 더 많은 자료를 발견하고 링크를 클릭하여 보았다 https://dev.to/quansightlabs/rethinking-jupyter-interactive-documentation-4okm텍스트를 자유롭게 공유하거나 복사할 수 있습니다.하지만 이 문서의 URL은 참조 URL로 남겨 두십시오.
우수한 개발자 콘텐츠 발견에 전념 (Collection and Share based on the CC Protocol.)