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

  • 相关阅读:
    spark视频-Spark Streaming实时计算和流处理
    spark视频-Spark把云计算大数据速度提高100倍以上
    spark视频-Spark on Docker深入揭秘
    spark视频-Spark as a Service
    spark视频-Spark on Yarn
    MyEclipse Web 项目导入 Eclipse 中需要改的文件
    【解决】小米M1刷机教程(卡刷)
    【解决】笔记本发射WiFi
    【解决】U盘装系统(Win7/Win8)& 装双系统
    【解决】Internet访问看似正常(无叹号受限)却打不开网页
  • 原文地址:https://www.cnblogs.com/zhuangzebo/p/6268964.html
Copyright © 2011-2022 走看看