软创互联

文档编写工具

sphinx
readthedocs

#1

Documentation options


sphinx

基础:

Sphinx 使用手册

搭建及应用:

30分钟教你快速搭建一个顔值超高的博客

Getting Started with Sphinx

使用ReadtheDocs托管文档

如何用 ReadtheDocs、Sphinx 快速搭建写书环境

https://build-me-the-docs-please.readthedocs.io/en/latest/Using_Sphinx/UsingGraphicsAndDiagramsInSphinx.html

示例:

Docker


MKDoc

https://www.mkdocs.org

https://hub.docker.com/r/squidfunk/mkdocs-material

使用 mkdocs 自动生成页面,文档中心。


docsify

示例:https://shd101wyy.github.io/markdown-preview-enhanced/#/zh-cn/


#2

使用ubuntu 11.10,用plantuml时生成中文乱码。
解决:

  1. 安装中文字库
    sudo apt-get install ttf-arphic-uming

  2. 在 plantuml 文件里加入

    skinparam defaultFontName ttf-arphic-uming


但是利用 java -jar plantuml.jar -tsvg test.uml 或者利用plantuml的vim插件命令 :make 都可以正常生成,但是里面的中文都是乱码。实在是让我发愁啊,在网上找了好久,只有一篇博客提到了这个问题,就是ubuntu plantuml的中文问题 。但这并不是我想要的,首先我的系统是Mac OS X,跟博文中的系统不一样,其次我的系统对中文编码是支持的,其他的都没问题,只是这里有问题。最后还是自己帮了自己,使用 java -jar plantuml.jar -h 可以看到有个 -charset 选项,但是后面说的默认编码格式却是GBK2312,总有找到问题了,于是我在命令里加了下面的参数 java -jar plantuml.jar -charset utf-8 -tsvg test.uml ,在看结果终于可以了~中文显示正常了!


#3

to pdf https://dormouse-youngs-blog.readthedocs.io/en/latest/rst-pdf.html

brew cask install mactex
export PATH=$PATH:/usr/local/texlive/2018/bin/x86_64-darwin/

make latex
cd build/latex
xelatex *.tex
open *.pdf

brew install fontconfig


参考资料

https://my.oschina.net/yangbajing/blog/170262


#4

Sphinx 攻略

Docker 快速搭建编写环境

  1. 在本机安装Docker环境
  2. docker pull dldl/sphinx-server

扩展

  1. plantuml http://plantuml.com/
  2. graphviz http://graphviz.org

#5

Example .rst File