zoukankan      html  css  js  c++  java
  • 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:

    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

  • 相关阅读:
    电脑与欧姆龙plc通过网络通信
    photometric_stereo halcon光度立体法三维表面重建
    WPF实现放大镜
    备忘
    Halcon模板匹配
    C# Halcon联合编程问题(二)
    C# Halcon混合编程中遇到的问题(一)
    各个平台的解释
    python数据结构的性能测试
    docker container里面为什么不用装OS
  • 原文地址:https://www.cnblogs.com/zhuangzebo/p/6268964.html
Copyright © 2011-2022 走看看