Write Markdown Syntax Online Document with Sphinx and Pandoc

仇睿

2023-12-01

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:

http://sphinx-doc.org/latest/tutorial.html

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

转载于:https://www.cnblogs.com/zhuangzebo/p/6268964.html