스핑크스(Sphinx)를 통해 만든 패키지의 레퍼런스 페이지를 만듭니다. 제가 제작하는 패키지 설명서는 튜토리얼과 레퍼런스 페이지를 분리하여 작업합니다. 튜토리얼 페이지는 패키지를 처음 접하는 사람들을 위해 작성하고, 레퍼런스 페이지는 패키지의 구조를 따라 문서를 구성하여 어느정도 패키지에 익숙한 사람들이 보는 용도로 작성합니다. 레퍼런스 페이지를 작성하는데 큰 수고를 들이지 않으려면 소스코드에 문서화문자열(docstring)을 잘 남겨두는것이 중요합니다. 관련글 Python 패키지 개발일지 05: 주석을 이용한 문서화 Python 패키지 개발일지 06: 스핑크스를 사용한 패키지 문서화 Python 패키지 개발일지 07: 스핑크스 개인화 Python 패키지 개발일지 08: 스핑크스 & 깃허브 페이지 (중..
Python 패키지 개발일지 10: 스핑크스 레퍼런스 페이지 만들기
패키지를 제작하다 보면 미묘하게 신경쓰이는데 이미 만들어놓은 구조 때문에 고치기가 난감한 문제들이 있습니다. 이대로 업데이트가 쌓이다 보면 조금 신경쓰이는 문제가 계속 남아 점점 기술부채가 증가하게 됩니다. 여기서는 패키지를 갈아엎게 만들었던 문제와 그 해결법을 다룹니다. 버전 규칙 기존 다른 패키지를 작업할 때는 버전 개념을 잘 몰라 업데이트 할 때마다 계속 숫자를 올리기만 했는데요. 이 때문에 업데이트의 규모와 성격을 알 수 없어서 관리하기가 복잡했던 경험이 있습니다. 현재 만들고 있는 AutoWinPy는 파이썬의 버전규칙과 동일한 세 구역으로 구분한 버전 규칙을 따르고 있습니다. 이 방식은 v1.6.32와 같은 형태를 가집니다. 세 번째 자리(예시의 32): 버그 수정 업데이트를 의미합니다. 두 번..
Python 패키지 개발일지 09: 패키지를 갈아엎게 하는 문제들
앞에서는 최소한의 설정으로 그럭저럭 깃허브 패키지 저장소와 스핑크스(Sphinx)를 연동하고 깃허브 페이지에 등록했습니다. 이번에는 배치파일 변경, 스핑크스의 깃허브 페이지 확장, 테마를 다룹니다. 관련글 Python 패키지 개발일지 07: 스핑크스 개인화 make.bat 변경 기존 make.bat을 백업하고 새로운 파일을 만듭니다. 이 배치파일은 페이지를 만든 후 자동으로 ./docs/html/ 안에 들어있는 파일을 ./docs/로 옮겨줍니다. @Echo Off set SPHINXBUILD=sphinx-build set SOURCEDIR=sphinx_source set BUILDDIR=docs %SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%..
Python 패키지 개발일지 08: 스핑크스 & 깃허브 페이지 (중급)
스핑크스(Sphinx)를 사용해 본격적으로 문서를 만들기 전에 만들어둔 깃허브(GitHub) 저장소와 스핑크스를 연동하는 작업을 하도록 하겠습니다. 이 작업은 반복 입력을 효과적으로 줄여줍니다. 관련 글 Python 패키지 개발일지 02: 깃허브에 패키지 올리기 Python 패키지 개발일지 03: PyPI에 패키지 올리기 Python 패키지 개발일지 06: 스핑크스를 사용한 패키지 문서화 readme.md 연결 index.rst와 readme.md를 연결하기 위해 m2r 패키지를 사용합니다. 명령창에 pip install m2r(아나콘다의 경우 conda install -c conda-forge m2r)를 입력하여 m2r을 설치한 후, conf.py를 열어 아래 내용으로 수정합니다. extensions ..
Python 패키지 개발일지 07: 스핑크스 개인화
스핑크스(Sphinx)는 파이썬 프로젝트를 문서화하는 도구입니다. 스핑크스는 RST(reStructuredText)와 파이썬의 문서화 문자열을 이용해 매뉴얼과 레퍼런스 문서를 작성하며 문서를 정적 웹페이지, 이북, PDF 등으로 출력합니다. 스핑크스 시작하기 > pip install Sphinx 아나콘다의 경우, > conda install -c anaconda sphinx 를 사용해 스핑크스를 설치합니다. 빠른 시작 프로젝트 디렉토리에서 다음 명령을 입력합니다. sphinx-quickstart 이제 스핑크스는 초기화를 위해 몇 가지를 물어봅니다. You have two options for placing the build directory for Sphinx output. Either, you use ..
Python 패키지 개발일지 06: 스핑크스를 사용한 패키지 문서화
특정한 위치에 있는 블록 주석은 요소의 __doc__속성이 되어 IntelliSense나 Sphinx등이 자동으로 설명을 붙일 수 있도록 해줍니다. 개발자가 아닌 사용자를 위한 이 주석은 별도로 docstring이라고 부르기도 합니다. 여기서는 Sphinx가 참조하는 구글 스타일의 주석과, Numpy스타일의 주석을 살펴봅니다. Docstring def function(a): """이것은 함수입니다. Args: a: 매개변수로 뭔가를 받습니다. Returns: 뭔가를 반환합니다. """ return a if __name__ == "__main__": print(function.__doc__) 지능형 코드 완성(IntelliSense) 기능을 제공하는 편집기는 이 __doc__를 자동으로 읽어 사용자에게 팝..
Python 패키지 개발일지 05: 주석을 이용한 문서화
Python은 "일단 작동은 하는 코드"와 "한눈에 기능을 알아볼 수 있는 코드"의 차이가 있습니다. 코딩할 때 알아보기 쉬운 방식으로 코드를 작성하면 유지관리에 도움이 됩니다. 또한, Sphinx를 사용해서 문서화를 할 때 엄청난 이득을 얻게 됩니다. 이름 짓기 예전과는 달리 VSCode와 같은 똑똑한 에디터들은 패키지를 가져오면 자동으로 모듈과 함수, 클래스의 이름을 가져옵니다. 마침표(.)를 입력하면 자동으로 선택메뉴가 나오고 화살표키로 선택한 뒤 엔터로 자동입력하는 방식이죠. 이 지능형 코드 완성(IntelliSense)기능을 최대한 활용하면 매번 패키지 소스코드를 들추지 않아도, 레퍼런스 문서를 뒤적이지 않아도 다음 일을 진행할 수 있으니 이 기능을 가진 편집기들을 많은 사람들이 사용하고 있습니..
Python 패키지 개발일지 04: 알기쉬운 파이썬 코드
이전 포스트에서는 깃허브(GitHub)에 패키지를 저장소 형태로 게시하는 방법을 소개했습니다. 이 작업은 깃허브 저장소를 패키지의 홈페이지로 사용하기 위한 것입니다. 무료로 소스코드와 홈페이지를 호스팅해주는 곳은 몇 군데 없으니까요. 게다가 버전관리와 이슈트래커 파일관리 협업 등 깃허브를 시용하는 것은 여러가지 이점을 가집니다. Python 패키지 개발일지 02: 깃허브에 패키지 올리기 이번에는 패키지를 배포하기 위한 파이썬 패키지 인덱스(PyPI)에 패키지를 업로드하여 다른 사람들이 손쉽게 만든 패키지를 이용할 수 있도록 하는 작업을 하도록 하겠습니다. PyPI 계정 등록 가장 먼저 PyPI에 계정을 생성해야 합니다. PyPI의 계정은 패키지를 프로젝트 단위로 관리할 수 있도록 해줍니다. 계정을 생성한..
Python 패키지 개발일지 03: PyPI에 패키지 올리기
일단 패키지를 온라인 저장소에 업로드한 뒤 파이썬 패키지 인덱스에 프로젝트를 등록하는 것 까지 해보도록 하겠습니다. 여기서는 각 과정과 그 과정에 필요한 서비스, 패키지, 응용프로그램들을 설명합니다. 깃허브 저장소 생성 깃허브(GitHub)에 계정을 등록한 후 저장소(Repository)를 생성합니다. 생성하는 저장소의 이름은 패키지 인덱스에 등록하는 이름과 직접적인 관련은 없으므로 여러개의 저장소를 관리한다거나 하는 경우에는 꼭 패키지 이름으로 하지 않아도 괜찮습니다. Initialize this repository with a README를 선택하면 아니라 복제와 편집이 가능한 저장소로 초기화합니다. 선택하지 않는 경우에 깃허브는 이 저장소를 위한 기존 저장소가 이미 있으며, 해당 저장소를 위해 자리..
Python 패키지 개발일지 02: 깃허브에 패키지 올리기
End of content
No more pages to load