Opensource Reference docs Site 를 오픈 하였습니다. 🙂

http://docs.crois.net 

블로그내용을 정리 하다 보니 너무 많이 시간이 걸려 markdown 을 이용하여 몇가지를 정리 하고 있습니다.

바로 쓸수 있는 Opensource Reference docs 을 만들려고 생각했는데 생각처럼 쉽지가 않군요.

일주일 남짓해서 FreeBSD , CentOS , Ubuntu , Docker 를 정리 하였습니다.

아직 정리할것이 너무 많은데 언제쯤 다 끝날지는 모르겠습니다.

혼자하기 싫어서 Project 란 말을 남기긴 하였지만… 누가 같이 만들어 줄지는…

차후 어느정도 Site 내용이 정리되면 같이 글을 쓰고 테스트를 하고 문서를 공유할수 있는 사람이 있었으면 좋겠네요.

 

 

 

Docker nginx + sphinx-doc install

 

 

Local 에서 sphinx 구성을 하지 않은 경우 웹페이지를 확인 하기 어렸습니다.

docker nginx + sphinx 를 간단하게 구성하는 방법을 포스팅 합니다.

sphinx-doc 설치는 아래 페이지를 참고 해 주세요.

Ubuntu sphinx-doc install

 

참고 페이지 : 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

https://github.com/rtfd/recommonmark

 

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 확인