如何在互联网发布你的doc

前提

Ubuntu 16.04.7 LTS
Ubuntu 22.04.1 LTS // 可略过 "1.python3.7 环境的安装" , 但需要安装 python3-pip

• 1.python3.7 环境的安装

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.7
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.7 2
sudo apt install python3-pip

• 2.sphinx的安装

wget https://bootstrap.pypa.io/get-pip.py
python3 get-pip.py
pip3 install sphinx // 会装到 ~/.local/bin
pip3 install sphinx_rtd_theme

• 3.pdf工具的安装

sudo apt-get install latexmk
sudo apt-get install texlive-xetex

• 4.字库的安装

sudo apt install font-manager  fonts-freefont-otf texlive-lang-chinese # 安装字体
fc-cache -f  #更新字体缓存

• 5.兼容markdown

不兼容的话,只能使用rst语法
pip install recommonmark
conf.py新增如下
extensions = ['recommonmark']

可以在 md 中同时使用  rst 和 md语法
可以在 rst 中使用 rst 语法

第一步 在 ubuntu 建立自己的 pdf 发布机制

export PATH= ~/.local/bin:$PATH
sphinx-quickstart \
	--sep \
	--dot=_ \
    -p project_name \
    -a suws \
    -v 1.0.0 -r 1.0.0 \
    -l zh_CN \
    --suffix=.rst  \
    --epub \
    --ext-imgmath  \
    --makefile \
    --no-batchfile \
    -q
sed  '/^html_theme/s/alabaster/sphinx_rtd_theme/' source/conf.py -i

make html
make latexpdf

第二步 上传工程到github

第三步 github 关联 到 https://readthedocs.org

1. 点击 import a project 按钮
2. 手动导入
3. 填写 名称 代码库地址 代码库类型 默认分支 
4. 构建

写DOC时遇到的一些问题及解决方案

• 如何链接到页面指定位置
  

页面中,如果有如图所示的图标,点击后,查看地址栏中的地址,例如 3_rel_dyn.html#rel-dyn
则在 markdown 格式的文件中可以如此索引
[目标链接](/path/to/file/3_rel_dyn.html#rel-dyn)

- [链接过程输入文件](汇编器.html#id3)

• 不支持表格

解决公式和表格显示问题
安装pandoc，在 github 上下载 deb 安装包，然后sudo dpkg -i $DEB安装.

用pandoc手动转换为rst

pandoc -s -t rst --toc newpage.md -o newpage.rst
指定sphinx显示rst文件

更改index.rst的内容

Welcome to learn_sphinx's documentation!
========================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   newpage.rst
然后创建make html, 再访问, 就可以正常显示公式和图表了。