Python文档工具 1970-01-01 00:00

程序员最讨厌的两件事情：给项目写文档和接手的项目没有文档。

介绍一个文档生成工具。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