Docker nginx + sphinx-doc install
Local 에서 sphinx 구성을 하지 않은 경우 웹페이지를 확인 하기 어렸습니다.
docker nginx + sphinx 를 간단하게 구성하는 방법을 포스팅 합니다.
sphinx-doc 설치는 아래 페이지를 참고 해 주세요.
참고 페이지 : https://github.com/serra/sphinx-with-markdown
https://docs.readthedocs.io/en/latest/getting_started.html
https://recommonmark.readthedocs.io/en/latest/#autostructify
https://recommonmark.readthedocs.io/en/latest/auto_structify.html
docker 및 docker-compose 설치를 합니다.
test@ubuntu-docs:~$ curl -s https://get.docker.com/ | sudo sh test@ubuntu-docs:~$ sudo usermod -aG docker test test@ubuntu-docs:~$ sudo curl -L https://github.com/docker/compose/releases/download/1.19.0/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose test@ubuntu-docs:~$ sudo chmod +x /usr/local/bin/docker-compose
docker-compose 대신 docker 만으로 사용하여도 됩니다.
docker-compose 에 사용할 디렉토리를 생성 합니다.
test@ubuntu-docs:~/Workspace$ mkdir web-docs test@ubuntu-docs:~/Workspace$ cd web-docs/ test@ubuntu-docs:~/Workspace/web-docs$ test@ubuntu-docs:~/Workspace/web-docs$ mkdir docs
docker-compose.yml 파일을 생성 합니다.
./nginx/conf 디렉토리와 /etc/nginx/conf.d 디렉토리를 연결 합니다.
./docs 디렉토리와 컨테이너의 /code 디렉토리를 연결 합니다.
test@ubuntu-docs:~/Workspace/web-docs$ vi docker-compose.yml
version: '2'
services:
nginx:
image: nginx:1.10.2
ports:
- 80:80
restart: always
volumes:
- ./nginx/conf:/etc/nginx/conf.d
- ./docs:/code
test@ubuntu-docs:~/Workspace/web-docs$ mkdir -p nginx/conf/
test@ubuntu-docs:~/Workspace/web-docs$ vi nginx/conf/default.conf
server {
listen 80 default_server;
server_name localhost _;
index index.html index.htm;
root /code;
location / {
autoindex on;
}
}
docker-compose 를 실행 합니다.
test@ubuntu-docs:~/Workspace/web-docs$ docker-compose up -d --build
컨테이너 구동 확인
test@ubuntu-docs:~/Workspace/web-docs$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES e0e37ee2dbbe nginx:1.10.2 "nginx -g 'daemon of…" 56 seconds ago Up 54 seconds 0.0.0.0:80->80/tcp, 443/tcp webdocs_nginx_1 test@ubuntu-docs:~/Workspace/web-docs$
sphinx 를 사용할 디렉토리로 이동 후 sphinx-quickstart 를 실행 합니다.
별도의 디렉토리를 지정 하지 않으면 sphinx-quickstart 를 실행한 디렉토리에 설정파일 등등이 생성 됩니다.
test@ubuntu-docs:~$ cd Workspace/web-docs/docs/ test@ubuntu-docs:~/Workspace/web-docs/docs$ sphinx-quickstart Welcome to the Sphinx 1.3.6 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Enter the root path for documentation. > Root path for the documentation [.]: You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]: The project name will occur in several places in the built documentation. > Project name: opensource docs > Author name(s): user01 Sphinx has the notion of a "version" and a "release" for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don't need this dual structure, just set both to the same value. > Project version: 1.0 > Project release [1.0]: If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see http://sphinx-doc.org/config.html#confval-language. > Project language [en]: ko The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]: One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]: Sphinx can also add configuration for epub output: > Do you want to use the epub builder (y/n) [n]: Please indicate if you want to use one of the following Sphinx extensions: > autodoc: automatically insert docstrings from modules (y/n) [n]: > doctest: automatically test code snippets in doctest blocks (y/n) [n]: > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: > coverage: checks for documentation coverage (y/n) [n]: > pngmath: include math, rendered as PNG images (y/n) [n]: > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: > ifconfig: conditional inclusion of content based on config values (y/n) [n]: > viewcode: include links to the source code of documented Python objects (y/n) [n]: A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: > Create Windows command file? (y/n) [y]: n Creating file ./conf.py. Creating file ./index.rst. Creating file ./Makefile. Finished: An initial directory structure has been created. You should now populate your master file ./index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck. test@ubuntu-docs:~/Workspace/web-docs/docs$
마크다운을 사용하기 위하여 recommonmark Python 패키지를 설치 합니다.
python-pip 패키지가 설치가 안되어 있을경우 설치를 먼저 진행합니다. $ sudo apt install python-pip 일반유저 에서 설치시 --user 옵션을 사용합니다. $ pip install recommonmark --user
conf.py 파일을 수정 합니다.
기존에 사용되던 source_suffix 라인은 주석 처리 합니다.
source_suffix 라인외의 항목은 수정이 아닌 추가된 항목 입니다.
2가지 경우로 설정 할수 있으며 markdown 고급기능에 따른 차이가? 있을수 있을거 같습니다.
자세한 내용은 링크 사이트를 참고해 주세요.
https://recommonmark.readthedocs.io/en/latest/ 설정시
test@ubuntu-docs:~/Workspace/web-docs/docs$ vi conf.py
#source_suffix = '.rst' <-- 주석 처리를 합니다.
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
from recommonmark.transform import AutoStructify
# At top on conf.py (with other import statements)
import recommonmark
from recommonmark.transform import AutoStructify
# At the bottom of conf.py
def setup(app):
app.add_config_value('recommonmark_config', {
'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
}, True)
app.add_transform(AutoStructify)
https://recommonmark.readthedocs.io/en/latest/auto_structify.html 설정시 아래와 같이 conf.py 를 설정합니다.
import sys
import os
import sphinx_rtd_theme
import recommonmark <-- 추가
#source_suffix = '.rst' <-- 기존 항목 주석처리
from recommonmark.parser import CommonMarkParser
from recommonmark.transform import AutoStructify
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
def setup(app):
app.add_config_value('recommonmark_config', {
'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
}, True)
app.add_transform(AutoStructify)
make html 을 실행 합니다.
test@ubuntu-docs:~/Workspace/web-docs/docs$ make html sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v1.8.1 loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 0 source files that are out of date updating environment: 2 added, 0 changed, 2 removed reading sources... [100%] test1 looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] test1 generating indices... genindex writing additional pages... search copying static files... done copying extra files... done dumping search index in English (code: en) ... done dumping object inventory... done build succeeded. The HTML pages are in _build/html. Build finished. The HTML pages are in _build/html. test@ubuntu-docs:~/Workspace/web-docs/docs$
테마를 설치 합니다.
test@ubuntu-docs:~/Workspace/web-docs/docs$ pip install sphinx_rtd_theme
테마를 적용합니다.
test@ubuntu-docs:~/Workspace/web-docs/docs$ vi conf.py import sphinx_rtd_theme #html_theme = 'alabaster' html_theme = 'sphinx_rtd_theme' html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
make html 을 실행 합니다.
test@ubuntu-docs:~/Workspace/web-docs/docs$ make html sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v1.3.6 loading translations [ko]... done loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: [config changed] 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindex writing additional pages... search copying static files... done copying extra files... done dumping search index in English (code: en) ... done dumping object inventory... done build succeeded. Build finished. The HTML pages are in _build/html. test@ubuntu-docs:~/Workspace/web-docs/docs$
web page 의 root page 는 /home/test/Workspace/web-docs/docs/_build/html 입니다.
docker-compose.yml 파일을 수정 해야 합니다. 🙂
test@ubuntu-docs:~/Workspace/web-docs/docs$ ls -al _build/html/ total 40 drwxrwxr-x 4 test test 4096 Sep 30 21:02 . drwxrwxr-x 4 test test 4096 Sep 30 21:02 .. -rw-rw-r-- 1 test test 230 Sep 30 21:02 .buildinfo -rw-rw-r-- 1 test test 2663 Sep 30 21:02 genindex.html -rw-rw-r-- 1 test test 3939 Sep 30 21:02 index.html -rw-rw-r-- 1 test test 228 Sep 30 21:02 objects.inv -rw-rw-r-- 1 test test 3045 Sep 30 21:02 search.html -rw-rw-r-- 1 test test 323 Sep 30 21:02 searchindex.js drwxrwxr-x 2 test test 4096 Sep 30 21:02 _sources drwxrwxr-x 2 test test 4096 Sep 30 21:02 _static test@ubuntu-docs:~/Workspace/web-docs/docs$
docker-compose down 및 docker-compose.yml 파일 수정
volumes 라인을 수정 합니다.
test@ubuntu-docs:~/Workspace/web-docs$ docker-compose down
test@ubuntu-docs:~/Workspace/web-docs$ vi docker-compose.yml
~중략
volumes:
- ./nginx/conf:/etc/nginx/conf.d
- ./docs/_build/html:/code
docker-compose 구동
test@ubuntu-docs:~/Workspace/web-docs$ docker-compose up -d --build
Web page 를 확인 합니다.
markdown test
test@ubuntu-docs:~/Workspace/web-docs/docs$ vi index.rst .. web-docs documentation master file, created by sphinx-quickstart on Mon Oct 1 18:59:13 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to web-docs's documentation! ==================================== Contents: .. toctree:: :maxdepth: 2 test1.md test2.md Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search
test1 / test2 메뉴 생성
test@ubuntu-docs:~/Workspace/web-docs/docs$ vi test1.md # test1 test@ubuntu-docs:~/Workspace/web-docs/docs$ vi test2.md # test2
make html 실행
test@ubuntu-docs:~/Workspace/web-docs/docs$ make html sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v1.8.1 loading translations [ko]... done loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 3 source files that are out of date updating environment: 3 added, 0 changed, 0 removed reading sources... [100%] test2 looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] test2 generating indices... genindex writing additional pages... search copying static files... done copying extra files... done dumping search index in English (code: en) ... done dumping object inventory... done build succeeded. The HTML pages are in _build/html. Build finished. The HTML pages are in _build/html. test@ubuntu-docs:~/Workspace/web-docs/docs$
web page 확인
