程序员最讨厌的两件事情:给项目写文档和接手的项目没有文档。
介绍一个文档生成工具。sphinx,据说Python的官方文档就是这货生成的。
但不是markdown语法写作不开心啊,你需要pandoc。
一个小伙伴发我的步骤:
1.==>To run doc, packages following should be installed:
apt-get install pandoc
apt-get install python-sphinx
2.==>How can we use it?
(1) mkdir doc && cd doc
(2)Run command: sphinx-quickstart
(3)After configuration:
You should now populate your master file ./source/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.
3.==>For the detail, checkout the link
http://sphinx-doc.org/latest/tutorial.html
4.==>Write doc
(1)Write your document with markdown syntax in directory source, such as
xx.md
yy.md
(2)Add content in file index.rst
xx
yy
5.==>Make doc
Run the following command:
bash run_doc.sh
6.==>Visit document
(1)add configure in nginx
location /doc/ {
alias path/doc/build/html/;
}
(2)visit document
http://yourdomain/doc/index.html
7.markdown editor
http://mahua.jser.me
run_doc.sh 脚本:
1 2 3 4 5 6 7 8 9 10 | #!/bin/bash
files=./source/*.md
for file in $files
do
pandoc "$file" -o "${file%.md}.rst"
done
make html
|
如果需要限制文档匿名访问。可以在alias上面加上这两行:参考
auth_basic "WTF,PASSWORD?";
auth_basic_user_file conf/htpasswd;
如何生成password,你可以下载nginx_auth.py.
python nginx_auth.py username password >> conf/htpasswd