우리 모두는 프로그래머가 코드를 작성한다는 것을 알고 있지만 우리 중 많은 사람들이 자신이 쓰기보다 읽기를 더 많이 한다는 사실을 인식하지 못합니다. 깨끗한 코드는 읽기가 더 쉬울 것입니다. 이 글에서는 쉽고 효과적인 방법으로 파이썬 코드 문서를 작성하고 출판하는 과정에 대해 설명하려고 합니다. 아래는 목차,

1. Write the standard docstring
2. Install Sphinx
3. Initialize Sphinx
4. Update the conf.py file
5. Auto generate the rst file
6. Build HTML
7. Publish the documentation online
8. Reference

1. 표준 독스트링 작성

Good programmers prefer to write the logic behind each class, methods, function etc using comments. In python, the best way to add the comments for the functions or class is to write in docstring format. Later, it can be used by documentation automation tools like sphnix 문서를 생성합니다. 그러나 자동화를 위해서는 standard docstring guideline을 따라야 합니다. 다음은 좋은 docstring 예제의 작은 예입니다.

def add(x, y):
    """Function to add two numbers 

        Parameters
        ----------
        x: int
            First number to add
        y: int
            Second number to add

        Returns
        -------
        int
            The sum of x and y
        """
    return x + y

2. 스핑크스 설치

Now next step is to install the sphnix. It can be installed easily using pip command,

pip install sphinx

3. 스핑크스 초기화

In the root directory of your project, run sphinx-quickstart to initialize the sphinx source directory to create a default configuration. I prefer to have separated directory for build and source , I hope you will also do the same.

sphinx-quickstart

Below image is the example of my sphinx-quickstart ,

위에 표시된 대로 sphinx-build 명령을 실행하면 Makefile , make.bat 파일과 build 및 source 디렉토리가 생성됩니다.

4. conf.py 파일 업데이트

The conf.py file is inside the source folder which describes the sphinx configurations to control the documentation. Here, I recommend you to overwrite the following things,

프로젝트 정보 추가

프로젝트 정보 섹션에서 copyright , author , release 등에 대해 업데이트해야 합니다. 다음은 내 프로젝트 정보의 예입니다.

# -- Project information -----------------------------------------------------

project = 'GeoTile'
copyright = '2022, Tek Kshetri'
author = 'Tek Kshetri'

# The full version, including alpha/beta/rc tags
release = '0.1.0'

확장 프로그램 추가

기본적으로 설명서에 확장이 추가되지 않습니다. 문서를 생성하려면 최소한 다음 확장자를 추가해야 합니다.

extensions = [
   'sphinx.ext.doctest',
   'sphinx.ext.autodoc',
   'sphinx.ext.autosummary',
   'sphinx.ext.napoleon',
]

테마 업데이트

스핑크스의 기본 테마는 alabaster 입니다. 이 외에도 여러 가지 테마가 있지만 개인적으로 pydata_sphinx_theme 를 좋아합니다. 테마를 변경하려면 먼저 터미널을 사용하여 테마를 설치해야 합니다.

pip install pydata_sphinx_theme

conf.py 파일로 업데이트하고,

# html theme for documentation
html_theme = "pydata_sphinx_theme"

이 테마를 사용자 지정하는 방법에는 여러 가지가 있습니다. 관심있는 분들은 official documentation of pydata_sphinx_theme 을 확인해주세요.

파이썬 모듈의 위치 지정

conf.py 파일의 맨 위에 주석이 달린 코드 줄이 표시됩니다. Python 코드 경로가 문서 디렉토리 외부에 있는 경우(대부분의 경우 이와 같음) 아래와 같이 코드 경로를 지정해야 합니다.

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

내 폴더 구조는 다음과 같습니다.

5. 첫 번째 파일 자동 생성

Sphinx generates the HTML documentation from reStructuredText (rst) files. To autogenerate the rst files, run the sphinx-apidoc command using following syntax:

sphinx-apidoc -o <OUTPUT_PATH> <MODULE_PATH>

In my case, the output directory is source , and the module directory is testCode . I have to run following command from documentation root folder,

sphinx-apidoc -f -o source ../testCode

The above command will create at least two files, modules.rst and test.rst . You can open it with any text editor and see the configuration or manually edit the things as well.

6. HTML 구축

Before building the HTML document, we need to insert the modules.rst file to source/index.rst file toctree . Please add the API reference <modules> to toctree as below,

.. toctree::
   :maxdepth: 2
   :caption: Test Documentation

   API reference <modules>

After that run the following command from your documentation root directory,

make html

This command will generate the html file inside the build directory. You can open it with any browser to check the documentation.

7. 온라인 설명서 게시

To publish the documentation, I am going to use Read the Docs 오픈 소스 솔루션. read the docs 를 사용하면 문서를 무료로 게시할 수 있습니다. 게시 지침은 다음과 같습니다.

계정 만들기

read the docs 계정이 없다면 create account read the docs 사이트에 로그인하세요.

프로젝트 가져오기

사용자 대시보드에는 프로젝트 가져오기 옵션이 있습니다. 옵션을 클릭하고 수동으로 가져오기 버튼을 다시 클릭합니다. 프로젝트 이름, 리포지토리 URL(문서에 대한 GitHub url) 및 기본 분기를 추가하고 다음을 클릭합니다.

프로젝트에 대한 추가 세부 정보를 다시 추가합니다.

마지막 단계는 버전을 빌드하고 문서를 보는 것입니다.

모든 작업을 올바르게 수행한 경우 문서 보기 버튼을 클릭하면 문서의 라이브 버전이 렌더링됩니다.

이 블로그 게시물이 유익한 정보가 되었기를 바랍니다. 이 블로그가 마음에 드시면 제 YouTube 채널을 구독하여 지원해 주세요.

8. 참조

Documenting python code (Blog post)

Automatic documentation generation from code (official documentation)

RST documentation guidline

Reference

이 문제에 관하여(자동으로 Python 코드 문서 작성 및 게시), 우리는 이곳에서 더 많은 자료를 발견하고 링크를 클릭하여 보았다 https://dev.to/iamtekson/write-and-publish-python-code-documentation-automatically-2bng

텍스트를 자유롭게 공유하거나 복사할 수 있습니다.하지만 이 문서의 URL은 참조 URL로 남겨 두십시오.

우수한 개발자 콘텐츠 발견에 전념 (Collection and Share based on the CC Protocol.)

자동으로 Python 코드 문서 작성 및 게시