Write Markdown Syntax Online Document with Sphinx and Pandoc

提示：扫一扫查出行
【扫一扫了解最新限行尾号】
复制提示

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:

2.Run command to configure environment:

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:

"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

Add the .md file name above in the file ./source/index.rst

4. Convert .md files to .rst files

We can write a script run_doc.sh:

After converting files, we can see doc1.rst, doc2.rst ... in the directory ./source

5. Convert .rst files to html files

You can see the html files under the directory: build/html

Attachment:

6. Visit online doc

Add configuration in Nginx:

Replace [directory] with your own home directory. Visit online doc:

Replace [website] with your own website.

7. Online markdown editor

Link: http://www.cnblogs.com/zhuangzebo/p/6268964.html