여러 부분으로 구성된 시리즈'시나리오의 변천'의 7부다.이 글의 코드는 Github에서 찾을 수 있습니다 (참조 here.

컨텐트

Clean and Self Descriptive Code

Comments, Docstrings and Git Commit Messages

README Files

Sphinx Documentation

본문에서, 나는python 세계에서 프로젝트를 어떻게 기록하는지 몇 가지 측면을 이야기하고 싶다.이것은 사용자나 다른 개발자들이 프로젝트를 하나의 전체적 또는 단독적인 부분으로 이해하기 쉽게 한다.우리는 최저 단계에서 시작하여 더욱 높은 추상적 단계로 매진할 것이다.

1. 깔끔하고 자기묘사 코드

최저 수준의 문서는 코드 자체다.읽을 수 있고 다시 사용할 수 있는 소프트웨어를 만드는 것이 목표다.이를 통해 다음과 같은 몇 가지 원칙을 따를 수 있습니다.

변수/함수/류의 의미 있고 발음 가능하며 일치하는 명칭.

단일 책임 원칙: 모든 함수는 하나의 목적만 실현하고 더욱 추상적인 등급의 클래스/모듈에도 적용된다.

비교적 큰 항목에 대해 정적 유형을 사용하고 mypy 강제 집행 유형 검사를 사용한다.파이썬과 같은 동적 언어는 대상 식별을 어렵게 한다.

바퀴의 재발명을 피하고 파이톤의 표준 라이브러리를 충분히 이용한다.우수한 개발자는 기존의 코드를 전략적으로 사용하여 자신의 장점을 발휘한다.

일치하는 스타일을 고수합니다. 저는 파이톤Googles styleguide을 좋아합니다.

코드가 우아하고 즐겁습니까?너의 직감에 따르면, 너의 잠재의식은 정확한 것을 가리킬 것이다.

2. docstring, 주석 및 Git 제출 메시지

>>> import math
>>> math.__doc__
'This module is always available.  It provides access to the'
'mathematical functions defined by the C standard.'

Docstrings는 함수, 클래스, 방법 또는 모듈 정의의 첫 번째 문장으로 나타나는 문자열 텍스트입니다.docstring은 이 대상의 __doc__ 특수 속성이 됩니다.그것들은 대상의 일반적인 용도를 설명하는 데 사용되고, 주석은 코드의 비교적 작은 부분을 설명한다.주석은 코드의 뚜렷하지 않은 부분을 설명하는 데 쓰인다.docstring은 """triple quotes"""에 둘러싸여 한 줄 또는 여러 줄로 나뉘고comments는 #로 시작한다.

def my_function():
    """This is a docstring"""
    return None

# docstring of the function
my_function.__doc__

# displays documentation of the function
help(my_function)

많은 docstring 형식을 사용할 수 있습니다.가장 일반적인 스타일은 NumPy, PyDoc 및 Google docstring 스타일입니다.파이썬 문서 생성기 Sphinx 를 지원하는 형식을 계속 사용하는 것은 좋은 생각입니다.문서의 일부분을 docstring에서 자동으로 생성합니다.본고의 마지막 부분에서는 Sphinx와readthedocs를 사용하여 문서를 생성하고 관리하는 방법을 보여 준다.
편리한 VScode 확장은 Python Docstring Generator 으로 docstring을 쉽게 만들 수 있습니다.

def multiply(x: int, y: int) -> int:
    """[summary]

    Args:
        x (int): [description]
        y (int): [description]

    Returns:
        int: [description]
    """
    return x * y

이것은 자동으로 파라미터를 검사할 것입니다. 표시된 필드만 기입하면 됩니다.기본적으로 구글 스타일을 사용한다.
프로젝트에 Git 히스토리가 있는 경우 다른 문서 소스를 사용할 수 있습니다.좋은git 역사 기록은 매번 코드가 변경되는 원인에 대한 정보를 제공할 수 있습니다.GitLens VScode의git 기능을 강화하여 제출한 코드 옆에서 제출한 메시지를 볼 수 있습니다.

그 밖에 저는 gitmoji를 사용하여 제출한 메시지의 읽기를 시각적으로 더욱 매력적으로 하고 gitmojis와 같은 코드 변경만 제출하도록 합니다.

3. 자술서

잘 작성된 읽어보기 파일은 프로젝트 방문자가 볼 첫 번째 문서입니다.다음은 셀프 호스팅용 IRC 클라이언트인 THELOUNGE의 화면 캡처입니다.

얼마나 아름다운 자술인가!이것은 무슨 좋은 점이 있습니까?

는 시각적으로 사람을 끌어당기고 잊을 수 없는 로고를 가지고 투명.png 이미지를 사용하여 Github의 명암 주제와 호환된다.

간결한 자기묘사.

shields.io에서 온 휘장으로 프로젝트의 질을 보여 줍니다.

문서 링크

예시, 프로그램이 실행될 때의 화면 캡처입니다.

에 포함된 피쳐 목록입니다.

일반적으로 읽어보기 파일에는 설치 지침이나 사용 설명서도 포함되어 있습니다.자술한 파일 형식은 .md (markdown) 또는 .rst (reStructuredText) 이다.때때로 사용자에게 흔히 볼 수 있는 예시를 제공하는 것도 좋은 생각이다.데이터 과학적 배경을 가진 프로젝트는 주피터 노트북.ipynb을 사용하여 프로젝트의 능력을 보여주는 경향이 있다.다른 항목은 일반python 파일을 사용하여 설명합니다.

4. 스핑크스 파일

작은 프로젝트README.md만으로도 충분하고 라이브러리와 같은 프로젝트는 더욱 광범위한 위탁 관리 기술 문서에서 이익을 얻을 수 있다.여기에서 저는 Sphinx, readthedocs와 Github Pages를 사용하여 자신의 무료 위탁 관리 문서를 만드는 것이 얼마나 간단한지 보여 드리겠습니다!
알겠습니다. 문서를 만들어 봅시다.Sphinx는 우리가 이 과정을 간소화하는 데 도움을 주는 도구다.

$ pip install sphinx

$ mkdir docs
$ cd docs

스핑크스는 우리에게 몇 가지 질문을 할 것이다.

$ sphinx-quickstart

> Separate source and build directories (y/n) [n]: y
> Project name: tinyHTTPie
> Author name(s): Niklas Tiede
> Project release []: 0.1.0
> Project language [en]: enter

문서를 만들려면 make html 디렉토리에서 docs 명령을 사용해야 합니다.그러면 문서의 HTML이 작성됩니다.

$ cd ..
$ make html

만약 우리가 라이브 서버를 통해 브라우저로 index.html 파일을 열면, 우리는 그것의 모습을 볼 수 있다.그러나 그것의 외관은 여전히 상당히 순수하다.따라서 우리는 유행하는 RTD 주제를 사용하여 전문적인 외관을 만들어 준다.우리는 테마를 설치한다...

$ pip install sphinx_rtd_theme

...그리고 사용자 정의conf.py 파일을 만듭니다.다음 행을 추가합니다.

import sphinx_rtd_theme

extensions = ["sphinx_rtd_theme",]
pygments_style = "sphinx"
version = '0.1.0'
html_theme = 'sphinx_rtd_theme'

그런 다음 다시 렌더링합니다.

$ make html

이제 많이 좋아진 것 같아!자, 이제 더 많은 내용을 쓰고 싶습니다.문서는 StructuredText(.rst) 구문을 사용하여 작성해야 합니다.이것은 괜찮은 것이다cheat sheet.IDE의 미리보기.rst가 빨라집니다.Tinyhtpie에 관한 문서를 추가했습니다. index.rst, install.rst, tutorial.rst 를 참고하십시오.마지막 단계는 우리의 문서를 발표하는 것이다.readthedocs.org에 등록하고 저장소에 연결해야 합니다.
봐라!예쁜 documentation가 만들어졌어요!나는 당신이 이렇게 보기 좋은 문서를 설정하는 것이 얼마나 쉬운지 보실 수 있기를 바랍니다. 문서 중에는 우리가 통상적으로 모르는 많은 재미있는 부분이 있습니다.😃