Sphinx로 문서화하고 Gitlab Pages에 배포하기

파이썬 프로젝트에 좋은 문서화 툴

pip install sphinx

sphinx-build . _build

이 글은

https://cpusuite.blogspot.com/2022/08/essentials-pycharm-ide-git.html

의 Pycharm setting essential이라는 글과 '나의 파이썬 프로젝트 초기 세팅법'이라는

제목으로 통합될 예정입니다.

GItlab pages를 통해 hosting을 하려면

특별한 룰을 따라야한다.

1번 룰 :
정적 컨텐츠는 반드시 public/  에 위치한다.

2번 룰 : 

artifacts 경로를 정의할 것.

artifacts with a path to the public/ directory must be defined

* artifacts란?

Job artifacts란 명세한 Job이 성공했는지, 실패했는지에 대한

파일과 경로의 리스트이다.


Job이 수행되면 Job이 어떤 형태로 완료되었는지 정보를 담은 파일을

경로에 저장한다.

pages:

  stage: deploy

  script:

    - mv docs/build/html/ public/

  artifacts:

    paths:

    - public

  only:

  - master

For further reference, an example sphinx project for GitLab Pages was pushed around the time you originally posted this question.

numpydoc_show_class_members = False

gitlab 호스팅을 위한 공식 가이드.

image: python:3.7-alpine

test:
  stage: test
  script:
  - pip install -U sphinx
  - sphinx-build -b html . public
  rules:
    - if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH
    
pages:
  stage: deploy
  script:
  - pip install -U sphinx
  - sphinx-build -b html . public
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

gitlab은 반드시 artifact를 public경로에 저장해야하는데,

source폴더에서 sphinx 빌드하고 public에 저장하려면 문제가 있다.

gitlab에서 요구하는 public경로는 root의 public이고

빌드하는 것은 한단계 아래의 source폴더이기 때문에

source폴더의 상위 폴더에 빌드를 시도할 경우 conf.py file을 포함하지 않는다는 에러를 낸다.

-> script에 파일 이동 명령어 기입함로 해결