Scop을 통한 Sphinx 환경 구축

의 목적

Windows에서 Sphinx를 사용하여 문서를 작성하는 환경html 및 pdf 출력
필요한 모듈의 설치를 단순화하려면 패키지 관리 도구scoop를 사용합니다.

성급한 사람을 향하다

성질이 급한 사람은 아래의 창고 Clone, 안에 있는 PowerShell 스크립트를 실행하십시오.
https://github.com/rhenerose/build_sphinx_environment_using_scoop

Scop 설치

먼저 Scoop를 설치하고 향후 작업에 필요한 모듈을 설치합니다.
PowerShell에서 다음 명령을 실행하십시오.
설치된 사용자Scoop는 이 프로그램을 따를 필요가 없습니다.
Scop 설치

# install scoop
Set-ExecutionPolicy RemoteSigned -scope CurrentUser
Invoke-Expression (New-Object System.Net.WebClient).DownloadString('https://get.scoop.sh')

# install basic module
scoop install aria2
scoop install git

# add bucket
scoop bucket add extras
scoop bucket add versions

정책 변경에 대한 정보가 표시되면 y를 입력하고 를 계속합니다.

파이썬 설치

설치된 사용자Python는 이 프로그램을 따를 필요가 없습니다.Scoop를 사용하여 Sphinx를 실행하는 데 필요한 Python를 설치합니다.
이 단계는 Python3.7가 설치되어 있습니다.
파이썬 설치

# install python3.7
scoop install python37

그런 다음 Sphinx의 가상 환경(venv)을 만듭니다.
이 단계에서는 가상 환경이 c:\venv\sphinx에서 제작될 것으로 예상하고 필요에 따라 변경하십시오.
가상 환경(venv)의 생성

# create venv
python37 -m venv c:\venv\sphinx
c:\venv\sphinx\Scripts\activate.ps1

# upgrade pip
python -m pip install --upgrade pip

Sphinx 설치 및 템플릿 프로젝트 작성

이후의 작업은 상술한 제작된 가상 환경에서 실행할 것을 구상한다.
환경에 대한 준비가 완료되었으므로 Sphix를 설치합니다.
Sphinx 설치

# install sphinx
pip install sphinx

Sphix가 설치되어 있으면 템플릿 프로젝트를 만듭니다.
이 단계는 c:\sphinx_doc에서 제작할 예정이므로 필요에 따라 변경하십시오.
템플릿 프로젝트 작성

# create project directory
mkdir c:\sphinx_doc
cd c:\sphinx_doc

# create template project
# 必要に応じてオプションの project, author, release を変更してください
sphinx-quickstart --sep --project='your_project' --author='your_name' --release='1.0.0' --language='ja'

여기에 지정된 옵션은 ./source/conf.py에 기재되어 있으며 이후에도 변경할 수 있습니다.

주제 수정

Sphinx 테마를 변경합니다.
주제에 관해서는 여기https://sphinx-themes.org/에서 좋아하는 것을 찾으세요.
이 단계에서 설치sphinx_rtd_theme합니다.
테마 설치

# install theme `sphinx_rtd_theme`
pip install sphinx_rtd_theme

다음 편집./source/conf.py 및 주제 변경
./source/conf.py

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Sphinx에서 Markdown 및 NoteBook 사용

Sphinx에서는 Markdown 및 NoteBook을 사용할 수 있습니다.
다양한 모듈 설치

# install other extention
# for `.md`
pip install recommonmark
pip install sphinx-markdown-tables

# for `.ipynb`
pip install ipython
pip install nbsphinx
scoop install pandoc

편집은 아래와 같다./source/conf.py.
conf.py

extensions = [
    'recommonmark',
    'nbsphinx',
    'sphinx.ext.mathjax',
    ]

source_suffix = ['.rst', '.md']
source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}

exclude_patterns = ['**.ipynb_checkpoints']

index.rst 업데이트

필요에 따라 업데이트index.rst하십시오.
예를 들어 Notebook 형식의 파일을 ./notebooks에 저장하여 파일로 만들 때 다음과 같은 내용으로 변경됩니다.
index.rst

.. toctree::
   :glob:

   notebooks/*

서류 제작

다음 명령을 실행하고 > 문서를 만듭니다.
서류 제작

# build html document
./make html

# 成果物の表示
./build/html/index.html

pdf 출력

Sphinx에서 PDF를 내보낼 수 있습니다.
scoop에 설치latex와perl, 변경conf.py의 설정.
LaTeX 설치

# install latex
scoop install latex
scoop install perl

./source/conf.py

# LaTeX設定
latex_engine = 'lualatex'

# LaTeXドキュメントクラスとしてltjsbookを使用する
latex_docclass = {'manual': 'ltjsbook'}

latex_elements = {
    'polyglossia': '',  #polyglossiaを読み込まない (大量エラー対策)
    'fontpkg': r'''
\setmainfont{DejaVu Serif}
\setsansfont{DejaVu Sans}
\setmonofont{DejaVu Sans Mono}
''',
    'preamble': r'''
\usepackage[titles]{tocloft}
\cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
\setlength{\cftchapnumwidth}{0.75cm}
\setlength{\cftsecindent}{\cftchapnumwidth}
\setlength{\cftsecnumwidth}{1.25cm}
''',
    'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
    'printindex': r'\footnotesize\raggedright\printindex',
}
latex_show_urls = 'footnote'
'''

pdf 문서 만들기

다음 명령을 실행하여pdf 문서를 만듭니다.
pdf 문서 만들기

# build pdf document
./make latexpdf

# 成果物の表示
./build/latex/*.pdf

처음 실행할 때 LaTex 설치에 필요한 모듈을 설치하려면 다음 대화 상자가 표시됩니다.
Install 버튼을 눌러 앞으로 이동합니다.

이 대화상자는 여러 번 표시됩니다. 만약 귀찮다면 빨간색 선 부분의 'Always show this daialog' 를 선택 취소하고 이 대화상자를 표시하지 않습니다.

Enjoy Sphinx!!

이만 마치겠습니다.
위 단계는 여기.에서 스크립트로 사용할 수 있습니다.
Sphinx로 끊임없이 문서를 만들어 봅시다!!