728x90 반응형 SMALL sphinx17 [Sphinx] Sphinx 프로젝트 온라인 배포 (3) HTML 문서 게시 1) 문서 읽기 문서는 GitHub 및 GitLab과의 통합을 제공한다. 시작하는 가장 빠른 방법 은 느슨하게 이 튜토리얼을 기반으로 하는 RTD 튜토리얼을 따르는 것이다. GitHub에 소스를 게시한 다음 문서 읽기 등록으로 바로 건너뛸 수 있다. 대신 GitLab을 선택하면 프로세스가 유사하다. 2) GitHub 페이지 GitHub 페이지를 사용 하려면 GitHub에 소스를 게시 해야한다. 그 후에 는 소스가 변경될 때마다 단계를 수행하는 자동화된 프로세스가 필요하다. GitHub Actions를 사용하여 달성할 수 있다. GitHub에 소스를 게시한 후 .github/workflows/sphinx.yml 다음 내용으로 리포지토리에 이름이 지정된 파일을 만든다. name: Sphi.. 2022. 5. 2. [Sphinx] Sphinx 프로젝트 온라인 배포 (2) 문서 소스 게시 (Publishing your documentation sources) 1) GitHub 기존 프로젝트를 GitHub에 업로드하는 가장 빠른 방법은 다음과 같다. GitHub 계정에 가입한다. 새 저장소를 만든다. 새 저장소의 "파일 업로드" 페이지를 연다. 운영 체제 파일 브라우저에서 파일 (README.rst, 디렉토리 lumache.py 아래의 makefiles 및 아래의 모든 파일)을 선택하고 GitHub 인터페이스로 끌어서 모두 업로드한다 (docsdocs/source). 변경 사항 커밋 버튼을 클릭한다. 이 단계에서는 명령줄에 액세스하거나 추가 소프트웨어를 설치할 필요가 없다. 자세히 알아보려면 다음을 수행한다. 대화형 GitHub 과정을 따라 GitHub 인터페이스 작동 방식.. 2022. 5. 2. [Sphinx] Sphinx 프로젝트 온라인 배포 (1) Sphinx 프로젝트 온라인 배포 (Deploying a Sphinx project online) 문서화 프로젝트를 세상에 보여줄 준비가 되면 많은 옵션을 사용할 수 있다. Sphinx에서 생성한 HTML은 정적이기 때문에 HTML 문서를 작성하는 프로세스를 선택한 플랫폼에서 이러한 파일을 호스팅하는 것과 분리할 수 있다. Python을 실행하는 정교한 서버가 필요하지 않습니다. 거의 모든 웹 호스팅 서비스로 충분하다. 따라서 문제는 정적 HTML을 제공하는 방법 또는 위치가 아니라 소스 파일이 변경될 때마다 배포된 문서를 자동으로 업데이트하는 워크플로를 선택하는 방법이다. 온라인 설명서를 배포하는 데 사용할 수 있는 몇 가지 옵션에 대해 설명하고 몇 가지 배경 정보를 제공한다. 실제 부분으로 직접 이동.. 2022. 5. 2. [Sphinx] 코드에서 자동 문서 생성 (2) 포괄적인 API 참조 생성 (Generating comprehensive API references) sphinx.ext.autodoc를 사용하면 코드와 문서의 동기화를 훨씬 쉽게 유지할 수 있지만 auto* 문서화하려는 모든 개체에 대한 지시문을 작성해야 한다. Sphinx는 또 다른 수준의 자동화인 자동 요약 확장을 제공한다. 지시문은 autosummary필요한 모든 autodoc지시문을 포함하는 문서를 생성한다. 이를 사용하려면 먼저 자동 요약 확장을 활성화한다. extensions = [ 'sphinx.ext.duration', 'sphinx.ext.doctest', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', ] api.rst다음 으로 다음 내용으로 새 .. 2022. 5. 2. [Sphinx] 코드에서 자동 문서 생성 (1) 코드에서 자동 문서 생성 (Automatic documentation generation from code) Sphinx의 Python 함수를 수동으로 문서화했다. 그러나 기능 서명이 동일하지 않았기 때문에 설명은 코드 자체와 동기화되지 않았다. 게다가 재사용하면 좋을 문서의 Python 독스트링은 두 곳에 정보를 작성하지 않아도 된다. 다행히 autodoc 확장은 이 기능을 제공한다. autodoc으로 서명 및 독스트링 재사용 autodoc을 사용하려면 먼저 활성화된 확장 목록에 autodoc을 추가한다. 다음으로 지시어의 내용을 다음과 같이 원본 Python 파일의 함수 docstring으로 이동한다 (py:function). def get_random_ingredients(kind=None): "".. 2022. 5. 2. [Sphinx] Describing code in Sphinx (Other languages) (2) 객체 문서화 및 상호 참조 (C, C++, others) Sphinx는 다른 프로그래밍 언어로 작성된 문서화 및 상호 참조 개체도 지원한다. C, C++, JavaScript 및 reStructuredText의 4가지 추가 기본 제공 도메인이 있다. 타사 확장은 다음과 같은 더 많은 언어에 대한 도메인을 정의할 수 있다. 포트란 줄리아 PHP 예를 들어, C++ 유형 정의를 문서화하려면 cpp:type 다음과 같이 내장 지시문을 사용한다. .. cpp:type:: std::vector CustomList A typedef-like declaration of a type. 다음과 같은 결과가 나타난다. # typedef 형식과 같은 선언 typedef std :: 벡터 CustomList 그.. 2022. 5. 2. [Sphinx] Describing code in Sphinx (Python) (1) Describing code in Sphinx Sphinx는 Python, C, C++, JavaScript 및 reStructuredText와 같은 여러 언어로 코드 개체 문서화를 지원한다. 각각은 도메인 별로 그룹화된 일련의 지시문 및 역할을 사용하여 문서화할 수 있다. 튜토리얼의 나머지 부분에서는 Python 도메인을 사용하지만 여기에서 볼 수 있는 모든 개념은 다른 도메인에도 적용된다. Python 객체 문서화 Sphinx는 Python 도메인에서 함께 그룹화된 Python 객체를 문서화하기 위한 여러 역할과 지시문을 제공한다 . 예를 들어, py:function다음과 같이 지시문을 사용하여 Python 함수를 문서화할 수 있다. Creating recipes ---------------- To .. 2022. 5. 2. [Sphinx] Narrative documentation in Sphinx (2) 상호 참조 추가 (Adding cross-references) Sphinx의 강력한 기능 중 하나는 문서, 섹션, 그림, 코드 개체 등과 같은 문서의 특정 부분에 상호 참조 를 원활하게 추가하는 기능이다. 상호 참조를 추가하려면 의 도입 단락 바로 뒤에 이 문장을 선언한다 index.rst. Check out the :doc:`usage` section for further information. 사용한 역할 은 프로젝트의 특정 문서를 자동으로 참조한다. 이 경우 이전에 생성한 것이다. doc usage.rst 또는 프로젝트의 임의 부분에 상호 참조를 추가할 수도 있다. 이를 위해 역할을 사용하고 대상 역할을 ref하는 명시적 레이블 을 추가해야 한다. 예를 들어, "설치" 하위 섹션을 참조하려면 다음과.. 2022. 5. 2. [Sphinx] Narrative documentation in Sphinx (1) 여러 페이지에 걸쳐 문서 구조화 (Structuring your documentation across multiple pages) index.rst에 의해 생성된 파일 sphinx-quickstart은 루트 문서이며, 주요 기능은 시작 페이지 역할을 하고 "목차 트리" (또는 toctree)의 루트를 포함하는 것이다. Sphinx를 사용하면 다른 파일에서 프로젝트를 조합할 수 있으므로 프로젝트가 커질 때 유용하다. 예를 들어, 다음 내용 으로 새 파일 docs/source/usage.rst (index.rst 옆에)을 만든다. Usage ===== Installation ------------ To use Lumache, first install it using pip: .. code-block:: co.. 2022. 5. 2. [Sphinx] More Sphinx customization (2) 타사 HTML 테마 사용 (Using a third-party HTML theme) 반면에 테마는 문서의 모양을 사용자 정의하는 방법입니다. Sphinx에는 몇 가지 기본 제공 테마 가 있으며 타사 테마도 있다. 예를 들어, HTML 문서에서 Furo 타사 테마를 사용하려면 먼저 다음과 같이 Python 가상 환경에 설치해야 한다. (.venv) $ pip install furo 그런 다음 html_theme에서 변수를 찾아 conf.py 값을 다음과 같이 바꾼다. # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'furo' 이 변경으로 인해 .. 2022. 5. 2. 이전 1 2 다음 728x90 반응형 LIST
