There is no doubt that we have to write doc while we are developing software. But How do you
write doc? I learnt a method to build a document by using markdown syntax with sphinx and pandoc.
It is quite elegant and convenient to use it. I am sure you will like it.
Firstly, I write the markdown doc in .md file, then I will convert it to .rst file. After converting the file,
I will use sphinx to convert it into HTML file, you can see the doc online. Here is the way as following on ubuntu:
1.To run doc and convert file, pakcages should be installed:
apt-get install pandoc apt-get install python-sphinx
2.Run command to configure environment:
sphinx-quickstart
After configuration, we can popluate master file source/index.rst and create other document source .rst file. Use the
Makefile to build the docs, like so:
make builder
"builder" is one te supported buidlers, e.g. html, latex or linkcheck.
Here is the turtorial:
3. Write doc
Under the directory ./source, we create source .md files, such as
doc1.md doc2.md ... docn.md
Add the .md file name above in the file ./source/index.rst
doc1
doc2
...
docn
4. Convert .md files to .rst files
We can write a script run_doc.sh:
#!/bin/bash
## run_doc.sh files=./source/*.md for file in $files do pandoc "$file" -o "${file%.md}.rst" done
After converting files, we can see doc1.rst, doc2.rst ... in the directory ./source
5. Convert .rst files to html files
make html
You can see the html files under the directory: build/html
Attachment:
#!/bin/bash ## run_doc.sh files=./source/*.md for file in $files do pandoc "$file" -o "${file%.md}.rst" done make html
6. Visit online doc
Add configuration in Nginx:
location /doc/ { alias [direcotry]/build/html/; }
Replace [directory] with your own home directory. Visit online doc:
http://[website]/doc/index.html
Replace [website] with your own website.
7. Online markdown editor
http://mahua.jser.me
Link: http://www.cnblogs.com/zhuangzebo/p/6268964.html