2024. 2. 3. 18:53ㆍpython/intermediate
코드를 문서화하는 것이 중요한 이유
"코드는 작성하는 것보다 읽는 경우가 더 많습니다."
— 귀도 반 로섬
코드를 작성할 때는 사용자와 개발자(자신 포함)라는 두 가지 주요 대상을 대상으로 작성합니다. 두 청중 모두 똑같이 중요합니다. 당신이 나와 같다면 아마도 오래된 코드베이스를 열어보고 "내가 대체 무슨 생각을 하고 있었던 거지?"라고 궁금해했을 것입니다. 자신의 코드를 읽는 데 문제가 있는 경우 사용자나 다른 개발자가 코드를 사용하거나 코드에 기여하려고 할 때 어떤 경험을 하는지 상상해 보세요.
반대로, Python으로 뭔가를 하고 싶었고 그 일을 완수할 수 있는 훌륭한 라이브러리처럼 보이는 상황에 직면했을 것이라고 확신합니다. 그러나 라이브러리를 사용하기 시작하면 특정 작업을 수행하는 방법에 대한 예제, 글 또는 공식 문서를 찾아보지만 즉시 해결책을 찾을 수는 없습니다.
검색 후에는 문서가 부족하거나 심지어 완전히 누락되었다는 사실을 깨닫게 됩니다. 이는 코드가 아무리 훌륭하고 효율적이더라도 라이브러리 사용을 방해하는 실망스러운 느낌입니다. Daniele Procida는 이 상황을 가장 잘 요약했습니다.
“소프트웨어가 얼마나 좋은지는 중요하지 않습니다. 왜냐하면 문서가 충분하지 않으면 사람들이 그것을 사용하지 않을 것이기 때문입니다. “
— 다니엘 프로치다
이 가이드에서는 사용자가 프로젝트를 사용하거나 기여하는 데 너무 좌절감을 느끼는 것을 방지하기 위해 가장 작은 스크립트부터 가장 큰 Python 프로젝트 까지 Python 코드를 적절하게 문서화하는 방법을 처음부터 배우게 됩니다 .
주석 달기와 코드 문서화
Python 코드를 문서화하는 방법을 설명하기 전에 문서화와 주석 달기를 구별해야 합니다.
일반적으로 주석 달기는 개발자에게/개발자를 위해 코드를 설명하는 것입니다. 의도된 주요 청중은 Python 코드의 관리자와 개발자입니다. 잘 작성된 코드와 함께 주석은 독자가 코드와 그 목적 및 디자인을 더 잘 이해할 수 있도록 안내하는 데 도움이 됩니다.
“코드는 방법을 알려줍니다. 댓글을 보면 그 이유를 알 수 있습니다.”
— Jeff Atwood (일명 코딩 호러)
코드를 문서화하는 것은 사용자에게 코드의 용도와 기능을 설명하는 것입니다. 개발 과정에서는 도움이 될 수 있지만 주요 대상은 사용자입니다. 다음 섹션에서는 코드에 주석을 추가하는 방법과 시기를 설명합니다.
주석 달기 코드의 기본
주석은 파운드 기호( #)를 사용하여 Python에서 생성되며, 몇 문장을 넘지 않는 간단한 설명이어야 합니다. 간단한 예는 다음과 같습니다
def hello_world():
# A simple comment preceding a simple print statement
print("Hello World")
PEP 8 에 따르면 주석의 최대 길이는 72자여야 합니다. 이는 프로젝트에서 최대 줄 길이를 권장되는 80자보다 크게 변경하는 경우에도 마찬가지입니다. 주석이 주석 문자 제한보다 클 경우 주석에 여러 줄을 사용하는 것이 적절합니다.
def hello_long_world():
# A very long statement that just goes on and on and on and on and
# never ends until after it's reached the 80 char limit
print("Hellooooooooooooooooooooooooooooooooooooooooooooooooooooooo World")
코드에 주석을 달면 다음과 같은 다양한 용도로 사용됩니다 .
- 계획 및 검토: 코드의 새로운 부분을 개발할 때 해당 코드 섹션을 계획하거나 개요를 설명하는 방법으로 먼저 주석을 사용하는 것이 적절할 수 있습니다. 실제 코딩이 구현되고 검토/테스트된 후에는 다음 주석을 제거해야 합니다.
# First step
# Second step
# Third step
- 코드 설명: 주석은 특정 코드 섹션의 의도를 설명하는 데 사용할 수 있습니다.
# Attempt a connection based on previous settings. If unsuccessful,
# prompt user for new settings.
- 알고리즘 설명: 알고리즘이 사용되는 경우, 특히 복잡한 알고리즘이 사용되는 경우, 알고리즘 작동 방식이나 코드 내에서 구현되는 방식을 설명하는 것이 유용할 수 있습니다. 특정 알고리즘이 다른 알고리즘보다 선택된 이유를 설명하는 것도 적절할 수 있습니다.
# Using quick sort for performance gains
- 태깅: 태깅을 사용하면 알려진 문제나 개선 영역이 있는 특정 코드 섹션에 레이블을 지정할 수 있습니다. 몇 가지 예는 BUG, FIXME및 TODO 입니다.
# TODO: Add condition for when val is None
- 코드에 대한 주석은 간결하고 집중적으로 작성해야 합니다. 가능하면 긴 주석을 사용하지 마세요. 또한 Jeff Atwood가 제안한 다음 네 가지 필수 규칙을 사용해야 합니다 .
- 설명하는 코드와 최대한 가깝게 주석을 유지하세요. 설명하는 코드 근처에 있지 않은 주석은 독자에게 불편을 주며 업데이트 시 쉽게 놓칠 수 있습니다.
- 복잡한 형식(예: 표 또는 ASCII 숫자)을 사용하지 마세요. 서식이 복잡하면 콘텐츠가 산만해지며 시간이 지나면서 유지 관리가 어려울 수 있습니다.
- 중복된 정보를 포함하지 마세요. 코드 독자가 프로그래밍 원리와 언어 구문에 대한 기본적인 이해를 갖고 있다고 가정합니다.
자체적으로 주석을 달도록 코드를 디자인하세요. 코드를 이해하는 가장 쉬운 방법은 코드를 읽는 것입니다. 명확하고 이해하기 쉬운 개념을 사용하여 코드를 디자인하면 독자는 신속하게 의도를 개념화할 수 있습니다.
의견은 귀하를 포함한 독자가 소프트웨어의 목적과 디자인을 이해하는 데 도움이 되도록 작성되었음을 기억하십시오.
유형 힌트를 통해 코드에 주석 달기(Python 3.5+)
유형 힌트는 Python 3.5에 추가되었으며 코드 독자를 돕기 위한 추가 양식입니다. 실제로 Jeff의 네 번째 제안이 위에서 다음 단계로 발전했습니다. 이를 통해 개발자는 주석을 달지 않고도 코드의 일부를 디자인하고 설명할 수 있습니다. 간단한 예는 다음과 같습니다.
def hello_name(name: str) -> str:
return(f"Hello {name}")
유형 힌트를 조사하면 함수가 입력이 name유형 str또는 문자열이 될 것으로 예상한다는 것을 즉시 알 수 있습니다 . 또한 함수의 예상 출력이 유형 str또는 문자열이 될 것임을 알 수 있습니다. 유형 힌트를 사용하면 주석을 줄이는 데 도움이 되지만 그렇게 하면 프로젝트 문서를 만들거나 업데이트할 때 추가 작업이 필요할 수도 있다는 점을 고려하십시요.
Docstring을 사용하여 Python 코드 베이스 문서화
이제 주석 달기에 대해 배웠으므로 Python 코드 기반 문서화에 대해 자세히 살펴보겠습니다. 이 섹션에서는 독스트링(docstring)과 이를 문서화에 사용하는 방법에 대해 배웁니다. 이 섹션은 다음과 같은 하위 섹션으로 더 세분화됩니다.
- Docstrings Background : Docstring이 Python 내에서 내부적으로 작동하는 방식에 대한 배경
- Docstring 유형 : 다양한 Docstring "유형"(함수, 클래스, 클래스 메소드, 모듈, 패키지 및 스크립트)
- Docstring 형식 : 다양한 Docstring “형식”(Google, NumPy/SciPy, reStructuredText 및 Epytext)
독스트링 배경
Python 코드 문서화는 모두 독스트링을 중심으로 이루어집니다. 이는 올바르게 구성되면 사용자와 프로젝트 문서 작성에 도움이 될 수 있는 내장 문자열입니다. 독스트링과 함께 Python help()에는 객체 독스트링을 콘솔에 인쇄하는 내장 함수도 있습니다 . 간단한 예는 다음과 같습니다.
help(str)
이 출력은 어떻게 생성됩니까? Python의 모든 것은 객체이므로 dir()명령을 사용하여 객체의 디렉터리를 검사할 수 있습니다. 이렇게 하고 무엇을 발견하는지 살펴봅시다:
dir(str)
해당 디렉터리 출력에는 흥미로운 속성인 __doc__이 있습니다. 해당 속성을 조사하면 다음을 발견할 수 있습니다.
print(str.__doc__)
객체 내에서 독스트링이 저장된 위치를 찾았습니다. 이는 해당 속성을 직접 조작할 수 있음을 의미합니다. 그러나 내장 기능에는 다음과 같은 제한 사항이 있습니다.
str.__doc__ = "I'm a little string doc! Short and stout; here is my input and print me for my out"
다른 사용자 정의 개체는 조작할 수 있습니다.
def say_hello(name):
print(f"Hello {name}, is it me you're looking for?")
say_hello.__doc__ = "A simple function that says hello... Richie style"
help(say_hello)
Python에는 Docstring 생성을 단순화하는 기능이 하나 더 있습니다. __doc__ 속성을 직접 조작하는 대신 객체 바로 아래에 문자열 리터럴을 전략적으로 배치하면 자동으로 __doc__ 값이 설정됩니다. 위와 동일한 예에서는 다음과 같은 일이 발생합니다.
def say_hello(name):
"""A simple function that says hello... Richie style"""
print(f"Hello {name}, is it me you're looking for?")
help(say_hello)
이제 독스트링의 배경을 이해하셨습니다. 이제 다양한 유형의 독스트링과 거기에 포함되어야 하는 정보에 대해 배울 시간입니다.
독스트링 유형
Docstring 규칙은 PEP 257 내에 설명되어 있습니다 . 그 목적은 사용자에게 개체에 대한 간략한 개요를 제공하는 것입니다. 유지 관리가 용이할 만큼 간결해야 하지만, 새로운 사용자가 목적과 문서화된 개체를 사용하는 방법을 이해할 수 있을 만큼 충분히 정교해야 합니다.
모든 경우에 독스트링은 삼중따옴표( """) 문자열 형식을 사용해야 합니다. 이는 독스트링이 여러 줄로 되어 있는지 여부에 관계없이 수행되어야 합니다. 최소한 독스트링은 설명하려는 내용에 대한 빠른 요약이어야 하며 한 줄에 포함되어야 합니다.
"""This is a quick summary line used as a description of the object."""
여러 줄로 된 독스트링은 요약을 넘어 객체를 더욱 자세히 설명하는 데 사용됩니다. 여러 줄로 된 모든 독스트링은 다음과 같은 부분으로 구성됩니다:
- 한 줄 요약 줄
- 요약을 진행하는 빈 줄
- 독스트링에 대한 추가 설명
- 또 다른 빈 줄
"""This is the summary line
This is the further elaboration of the docstring. Within this section,
you can elaborate further on details as appropriate for the situation.
Notice that the summary and the elaboration is separated by a blank new
line.
"""
# Notice the blank line above. Code should continue on this line.
모든 독스트링은 주석과 동일한 최대 문자 길이(72자)를 가져야 합니다. Docstring은 세 가지 주요 범주로 더 나눌 수 있습니다.
- 클래스 Docstring: 클래스 및 클래스 메소드
- 패키지 및 모듈 Docstring: 패키지, 모듈 및 함수
- 스크립트 Docstring: 스크립트 및 함수
클래스 독스트링
클래스 Docstring은 클래스 자체는 물론 모든 클래스 메소드에 대해 생성됩니다. 독스트링은 한 수준 들여쓰기된 클래스 또는 클래스 메서드 바로 뒤에 배치됩니다.
class SimpleClass:
"""Class docstrings go here."""
def say_hello(self, name: str):
"""Class method docstrings go here."""
print(f'Hello {name}')
클래스 독스트링에는 다음 정보가 포함되어야 합니다:
- 목적과 동작에 대한 간략한 요약
- 간단한 설명과 함께 공개 메소드
- 모든 클래스 속성(속성)
- 클래스가 서브클래싱되도록 의도된 경우 서브클래서용 인터페이스 와 관련된 모든 것
클래스 생성자 매개변수는 __init__ 클래스 메소드 docstring 내에 문서화되어야 합니다. 개별 메서드는 개별 독스트링을 사용하여 문서화해야 합니다. 클래스 메소드 독스트링은 다음을 포함해야 합니다:
- 방법이 무엇인지, 어떤 용도로 사용되는지에 대한 간략한 설명
- 키워드 인수를 포함하여 전달되는 모든 인수(필수 및 선택 사항 모두)
- 선택 사항으로 간주되거나 기본값이 있는 인수에 레이블을 지정합니다.
- 메서드를 실행할 때 발생하는 모든 부작용
- 발생한 모든 예외
- 메서드를 호출할 수 있는 시기에 대한 제한 사항
동물을 나타내는 데이터 클래스의 간단한 예를 들어보겠습니다. 이 클래스에는 몇 가지 클래스 속성, 인스턴스 속성, __init__ 및 단일 인스턴스 메서드가 포함됩니다 .
class Animal:
"""
A class used to represent an Animal
...
Attributes
----------
says_str : str
a formatted string to print out what the animal says
name : str
the name of the animal
sound : str
the sound that the animal makes
num_legs : int
the number of legs the animal has (default 4)
Methods
-------
says(sound=None)
Prints the animals name and what sound it makes
"""
says_str = "A {name} says {sound}"
def __init__(self, name, sound, num_legs=4):
"""
Parameters
----------
name : str
The name of the animal
sound : str
The sound the animal makes
num_legs : int, optional
The number of legs the animal (default is 4)
"""
self.name = name
self.sound = sound
self.num_legs = num_legs
def says(self, sound=None):
"""Prints what the animals name is and what sound it makes.
If the argument `sound` isn't passed in, the default Animal
sound is used.
Parameters
----------
sound : str, optional
The sound the animal makes (default is None)
Raises
------
NotImplementedError
If no sound is set for the animal or passed in as a
parameter.
"""
if self.sound is None and sound is None:
raise NotImplementedError("Silent Animals are not supported!")
out_sound = self.sound if sound is None else sound
print(self.says_str.format(name=self.name, sound=out_sound))
패키지 및 모듈 독스트링
패키지 독스트링은 패키지 __init__.py 파일의 맨 위에 배치되어야 합니다. 이 독스트링은 패키지가 내보낸 모듈과 하위 패키지를 나열해야 합니다.
모듈 독스트링은 클래스 독스트링과 유사합니다. 클래스와 클래스 메서드가 문서화되는 대신 이제는 모듈과 그 안에 있는 모든 함수입니다. 모듈 독스트링은 가져오기 전에도 파일 상단에 배치됩니다. 모듈 독스트링에는 다음이 포함되어야 합니다:
- 모듈과 그 목적에 대한 간략한 설명 -모듈에서 내보낸 모든 클래스, 예외, 함수 및 기타 개체 목록
모듈 함수의 독스트링은 클래스 메소드와 동일한 항목을 포함해야 합니다:
- 함수가 무엇인지, 어떤 용도로 사용되는지에 대한 간략한 설명
- 키워드 인수를 포함하여 전달되는 모든 인수(필수 및 선택 사항 모두)
- 선택사항으로 간주되는 인수에 라벨을 지정하세요.
- 함수 실행 시 발생하는 모든 부작용
- 발생한 모든 예외
- 함수를 호출할 수 있는 시기에 대한 제한사항
스크립트 독스트링
스크립트는 콘솔에서 실행되는 단일 파일 실행 파일로 간주됩니다. 스크립트에 대한 Docstring은 파일 상단에 배치되며 사용자가 스크립트 사용 방법을 충분히 이해할 수 있도록 충분히 문서화되어야 합니다. 사용자가 매개변수를 잘못 전달하거나 -h 옵션을 사용할 때 "사용" 메시지에 사용할 수 있어야 합니다.
argparse를 사용하는 경우, 매개변수별 문서가 argparser.parser.add_argument 함수의 help 매개변수 내에 올바르게 문서화되어 있다고 가정하여 매개변수별 문서를 생략할 수 있습니다. argparse.ArgumentParser의 description 내 매개변수에 __doc__를 사용하는 것이 좋습니다. 어떻게 argparse 사용할 지 및 기타 일반적인 명령줄 파서에 대한 자세한 내용은 명령줄 구문 분석 라이브러리에 대한 튜토리얼을 확인하세요.
마지막으로 사용자가 스크립트를 실행하는 데 필요한 패키지를 알 수 있도록 사용자 정의 또는 타사 가져오기가 독스트링 내에 나열되어야 합니다. 다음은 스프레드시트의 열 헤더를 간단히 인쇄하는 데 사용되는 스크립트의 예입니다.
"""Spreadsheet Column Printer
This script allows the user to print to the console all columns in the
spreadsheet. It is assumed that the first row of the spreadsheet is the
location of the columns.
This tool accepts comma separated value files (.csv) as well as excel
(.xls, .xlsx) files.
This script requires that `pandas` be installed within the Python
environment you are running this script in.
This file can also be imported as a module and contains the following
functions:
* get_spreadsheet_cols - returns the column headers of the file
* main - the main function of the script
"""
import argparse
import pandas as pd
def get_spreadsheet_cols(file_loc, print_cols=False):
"""Gets and prints the spreadsheet's header columns
Parameters
----------
file_loc : str
The file location of the spreadsheet
print_cols : bool, optional
A flag used to print the columns to the console (default is
False)
Returns
-------
list
a list of strings used that are the header columns
"""
file_data = pd.read_excel(file_loc)
col_headers = list(file_data.columns.values)
if print_cols:
print("\n".join(col_headers))
return col_headers
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
'input_file',
type=str,
help="The spreadsheet file to pring the columns of"
)
args = parser.parse_args()
get_spreadsheet_cols(args.input_file, print_cols=True)
if __name__ == "__main__":
main()
독스트링 형식
Arguments이 튜토리얼에 제공된 예제 전반에 걸쳐 공통 요소인 , Returns및 Attributes와 같은 특정 형식이 있음을 알 수 있습니다. 독스트링 파서와 사용자가 익숙하고 알려진 형식을 갖는 데 도움이 되는 특정 독스트링 형식이 있습니다. 이 튜토리얼의 예제에서 사용된 형식은 NumPy/SciPy 스타일 Docstring입니다. 가장 일반적인 형식 중 일부는 다음과 같습니다.
서식 유형설명스핑크스에서 지원공식 사양| 구글 독스트링 | Google에서 권장하는 문서 형식 | 예 | 아니요 |
| 재구성된 텍스트 | 공식 Python 문서 표준; 초보자에게 친숙하지는 않지만 기능이 풍부합니다. | 예 | 예 |
| NumPy/SciPy 독스트링 | NumPy의 reStructuredText와 Google Docstring의 조합 | 예 | 예 |
| 에피텍스트 | Epydoc을 Python으로 적용한 것입니다. Java 개발자에게 적합 | 공식적으로는 아님 | 예 |
독스트링 형식의 선택은 귀하에게 달려 있지만 문서/프로젝트 전반에 걸쳐 동일한 형식을 고수해야 합니다. 다음은 각 문서 형식이 어떻게 보이는지에 대한 아이디어를 제공하는 각 유형의 예입니다.
Google Docstring 예제
"""Gets and prints the spreadsheet's header columns
Args:
file_loc (str): The file location of the spreadsheet
print_cols (bool): A flag used to print the columns to the console
(default is False)
Returns:
list: a list of strings representing the header columns
"""
reStructuredText 예
"""Gets and prints the spreadsheet's header columns
:param file_loc: The file location of the spreadsheet
:type file_loc: str
:param print_cols: A flag used to print the columns to the console
(default is False)
:type print_cols: bool
:returns: a list of strings representing the header columns
:rtype: list
"""
NumPy/SciPy Docstring 예제
"""Gets and prints the spreadsheet's header columns
Parameters
----------
file_loc : str
The file location of the spreadsheet
print_cols : bool, optional
A flag used to print the columns to the console (default is False)
Returns
-------
list
a list of strings representing the header columns
"""
에피텍스트 예
"""Gets and prints the spreadsheet's header columns
@type file_loc: str
@param file_loc: The file location of the spreadsheet
@type print_cols: bool
@param print_cols: A flag used to print the columns to the console
(default is False)
@rtype: list
@returns: a list of strings representing the header columns
"""
Python 프로젝트 문서화
Python 프로젝트는 모든 종류의 모양, 크기 및 목적으로 제공됩니다. 프로젝트를 문서화하는 방식은 특정 상황에 적합해야 합니다. 프로젝트 사용자가 누구인지 염두에 두고 그들의 요구에 적응하세요. 프로젝트 유형에 따라 문서의 특정 측면이 권장됩니다. 프로젝트와 문서의 일반적인 레이아웃은 다음과 같아야 합니다.
프로젝트는 일반적으로 프라이빗, 공유, 퍼블릭/오픈 소스의 세 가지 주요 유형으로 나눌 수 있습니다.
개인 프로젝트
비공개 프로젝트는 개인적인 용도로만 사용하도록 고안된 프로젝트이며 일반적으로 다른 사용자나 개발자와 공유되지 않습니다. 이러한 유형의 프로젝트에서는 문서화가 매우 가벼울 수 있습니다. 필요에 따라 추가할 수 있는 몇 가지 권장 부품이 있습니다.
- 읽어보기: 프로젝트와 목적에 대한 간략한 요약입니다. 프로젝트 설치 또는 운영에 대한 특별한 요구 사항을 포함하십시오.
- examples.py: 프로젝트 사용 방법에 대한 간단한 예를 제공하는 Python 스크립트 파일입니다.
개인 프로젝트가 귀하를 개인적으로 위한 것이지만 귀하도 사용자로 간주된다는 점을 기억하십시오. 앞으로 혼란스러울 수 있는 모든 것에 대해 생각하고 주석, 독스트링 또는 추가 정보에 해당 내용을 캡처하십시오.
공유 프로젝트
공유 프로젝트는 프로젝트 개발 및/또는 사용에 있어 다른 몇몇 사람들과 협력하는 프로젝트입니다. 프로젝트의 "고객" 또는 사용자는 계속해서 자신과 프로젝트를 사용하는 제한된 소수입니다.
문서화는 비공개 프로젝트에 필요한 것보다 좀 더 엄격해야 합니다. 주로 새 구성원을 프로젝트에 참여시키는 데 도움을 주거나 기여자/사용자에게 프로젝트의 새로운 변경 사항을 알리는 데 도움이 됩니다. 프로젝트에 추가할 권장 부분은 다음과 같습니다.
- 읽어보기: 프로젝트와 목적에 대한 간략한 요약입니다. 프로젝트 설치 또는 운영에 대한 특별한 요구 사항을 포함하십시오. 또한 이전 버전 이후의 주요 변경 사항을 추가하세요.
- examples.py: 프로젝트 사용 방법에 대한 간단한 예를 제공하는 Python 스크립트 파일입니다.
- 기여 방법: 여기에는 프로젝트에 새로운 기여자가 기여를 시작할 수 있는 방법이 포함되어야 합니다.
공개 및 오픈 소스 프로젝트
공개 및 오픈 소스 프로젝트는 대규모 사용자 그룹과 공유하기 위한 프로젝트이며 대규모 개발 팀이 참여할 수 있습니다. 이러한 프로젝트는 프로젝트 자체의 실제 개발만큼 프로젝트 문서화에 높은 우선순위를 두어야 합니다. 프로젝트에 추가할 권장 부분은 다음과 같습니다.
- 읽어보기: 프로젝트와 목적에 대한 간략한 요약입니다. 프로젝트 설치 또는 운영에 대한 특별한 요구 사항을 포함하십시오. 또한 이전 버전 이후의 주요 변경 사항을 추가하세요. 마지막으로, 추가 문서, 버그 보고 및 프로젝트에 대한 기타 중요한 정보에 대한 링크를 추가하세요.
- 기여 방법: 여기에는 프로젝트에 새로운 기여자가 어떻게 도움을 줄 수 있는지가 포함되어야 합니다. 여기에는 새로운 기능 개발, 알려진 문제 해결, 문서 추가, 새 테스트 추가 또는 문제 보고가 포함됩니다.
- 행동 강령: 소프트웨어를 개발하거나 사용할 때 다른 기여자가 서로를 어떻게 대해야 하는지 정의합니다. 또한 이 코드가 손상되면 어떤 일이 발생하는지 명시합니다. Github를 사용하는 경우 권장 문구가 포함된 행동 강령 템플릿을 생성할 수 있습니다. 특히 오픈 소스 프로젝트의 경우 이것을 추가하는 것을 고려해보세요.
- 라이선스: 프로젝트에서 사용 중인 라이선스를 설명하는 일반 텍스트 파일입니다. 특히 오픈 소스 프로젝트의 경우 이것을 추가하는 것을 고려해보세요.
- docs: 추가 문서가 포함된 폴더입니다. 다음 섹션에서는 포함해야 할 내용과 이 폴더의 내용을 구성하는 방법에 대해 자세히 설명합니다.
docs폴더 의 네 가지 주요 섹션
Daniele Procida는 Python 프로젝트 문서화에 관한 멋진 PyCon 2017 강연 과 후속 블로그 게시물을 제공했습니다 . 그는 작업에 집중하는 데 도움이 되도록 모든 프로젝트에 다음과 같은 네 가지 주요 섹션이 있어야 한다고 언급합니다.
- 자습서 : 독자가 일련의 단계를 거쳐 프로젝트(또는 의미 있는 연습)를 완료하도록 안내하는 강의입니다. 사용자의 학습에 맞춰져 있습니다. How-To 가이드 : 독자에게 일반적인 문제를 해결하는 데 필요한 단계를 안내하는 가이드(문제 중심 레시피).
- 참고문헌 : 특정 주제를 명확하게 하고 조명하는 설명입니다. 이해를 지향합니다.
- 설명 : 기계에 대한 기술적 설명과 작동 방법(주요 클래스, 기능, API 등)입니다. 백과사전 기사를 생각해 보세요.
다음 표에서는 이러한 모든 섹션이 서로 어떻게 연관되어 있는지와 전체적인 목적을 보여줍니다.
공부할 때 가장 유용함코딩할 때 가장 유용함| 실제 단계 | 튜토리얼 | 방법 가이드 |
| 이론적 지식 | 설명 | 참조 |
결국, 사용자가 어떤 질문에 대한 답변에 액세스할 수 있는지 확인하고 싶을 것입니다. 이러한 방식으로 프로젝트를 구성하면 이러한 질문에 쉽게 답할 수 있고 빠르게 탐색할 수 있는 형식으로 만들 수 있습니다.
문서 도구 및 리소스
코드, 특히 대규모 프로젝트를 문서화하는 것은 어려울 수 있습니다. 다행히도 시작하는 데 도움이 되는 몇 가지 도구와 참고 자료가 있습니다.
도구설명| 스핑크스 | 다양한 형식의 문서를 자동 생성하는 도구 모음 |
| 에피독 | 독스트링을 기반으로 Python 모듈에 대한 API 문서를 생성하기 위한 도구 |
| 문서 읽기 | 문서 자동 작성, 버전 관리 및 호스팅 |
| 독시젠 | Python 및 기타 여러 언어를 지원하는 문서를 생성하기 위한 도구 |
| MkDocs | Markdown 언어를 사용하여 프로젝트 문서를 작성하는 데 도움이 되는 정적 사이트 생성기입니다. |
| 피코 | 코드와 문서를 나란히 표시하는 "빠르고 더러운" 문서 생성기입니다. |
| doctest | 사용 예제를 자동화된 테스트로 실행하기 위한 표준 라이브러리 모듈입니다. python의 doctest를 확인하세요 : 코드를 한 번에 문서화하고 테스트하세요 |
이러한 도구와 함께 프로젝트를 문서화할 때 유용할 수 있는 몇 가지 추가 튜토리얼, 비디오 및 기사가 있습니다.
- Carol Willing - 실용적인 스핑크스 - PyCon )2018(https://www.youtube.com/watch?v=0ROZRNZkPS8)
- Daniele Procida - 문서 중심 개발 - Django 프로젝트에서 얻은 교훈 - PyCon 2016(https://www.youtube.com/watch?v=bQSR1UpUdFQ)
- Eric Holscher - Sphinx로 프로젝트 문서화 및 문서 읽기 - PyCon 2016(https://www.youtube.com/watch?v=hM4I58TA72g)
- Titus Brown, Luiz Irber - Python 프로젝트 생성, 빌드, 테스트 및 문서화: 실습 방법 - PyCon 2016(https://youtu.be/SUt3wT43AeM?t=6299)
- reStructuredText 공식 문서(http://docutils.sourceforge.net/rst.html)
- 스핑크스의 reStructuredText 입문서(http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
- Sphinx로 Python 프로젝트 문서화 및 문서 읽기(https://realpython.com/courses/python-sphinx/)
- ChatGPT로 Python 코드와 프로젝트를 문서화(https://realpython.com/document-python-code-with-chatgpt/)
때로는 배우는 가장 좋은 방법은 다른 사람을 모방하는 것입니다. 문서를 잘 활용하는 훌륭한 프로젝트의 예는 다음과 같습니다.
어디서부터 시작해야 합니까?
프로젝트 문서화는 간단한 진행 방식을 따릅니다.
- 문서 없음
- 일부 문서
- 완전한 문서
- 좋은 문서
- 훌륭한 문서
문서의 다음 단계를 어디로 가야할지 모르겠다면 위의 진행 상황과 관련하여 프로젝트가 현재 어디에 있는지 살펴보세요. 문서가 있나요? 그렇지 않다면 거기에서 시작하십시오. 일부 문서가 있지만 주요 프로젝트 파일 중 일부가 누락된 경우 해당 문서를 추가하여 시작하세요.
'python > intermediate' 카테고리의 다른 글
| ChatGPT로 Python 코드와 프로젝트를 문서화하세요 II (0) | 2024.02.05 |
|---|---|
| ChatGPT로 Python 코드와 프로젝트를 문서화하세요 I (0) | 2024.02.04 |
| 향상된 노트북 경험을 위한 JupyterLab II (0) | 2024.02.02 |
| 향상된 노트북 경험을 위한 JupyterLab I (1) | 2024.02.01 |
| Python의 배열-숫자 데이터를 효율적으로 사용하기 II (1) | 2024.01.31 |