pkgdown | readthedocs | 为工具撰写使用文档
2023年01月12日
注意：要用conda进入r4p3进行开发。
发现了pkgdown可能更适配R包，而readthedocs则适合shell和Python。
用pkgdown来开发R包的网站，非常方便。
准备工作：
- 开发、编译、安装好的R包
- 基本工具，如pkgdown
- https://pandoc.org/installing.html
requiredPackages = c('pkgdown','knitr','rmarkdown','jsonlite','sp')
for(p in requiredPackages){
if(!require(p,character.only = TRUE)) install.packages(p)
library(p,character.only = TRUE)
}
真的非常简单，就是几个静态的html网页，直接用jupyter导出就行，在配置文件里配置一下即可，非常傻瓜简洁，而且也很专业美观。
注意配置文件_pkgdown.yml的换行缩进即可。
参考：
- https://smorabit.github.io/hdWGCNA/reference/index.html
- https://github.com/smorabit/hdWGCNA/blob/dev/_pkgdown.yml
- https://bootswatch.com/ 【可选的主题】
之前有教程：bookdown - 撰写和发表自己的网络书籍/文档
现在发现readthedocs可能更简单，更适合页数不多的文档，可以适配Jupyter notebooks in Sphinx，分析做好，注释好，文档就也做完了。
管理：https://readthedocs.org/projects/bt3m-multimodal/
参考：
- https://github.com/cistrome/MIRA
- https://mira-multiome.readthedocs.io/en/latest/index.html
- 这个主题比较美观：https://rtd-sphinx-theme-sample-project.readthedocs.io/en/alabaster/
Read the Docs tutorial
https://docs.readthedocs.io/en/stable/tutorial/ 【主要就是clone一下template文档】
https://readthedocs.org/dashboard/ 【import一下】
https://github.com/leezx/bt3m-multimodal
build
https://bt3m-multimodal.readthedocs.io/en/latest/
主要配置
github desktop下载同步该仓库
最简单
配置改theme
https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html
https://rtd-sphinx-theme-sample-project.readthedocs.io/en/alabaster/
https://github.com/bitprophet/alabaster/
https://alabaster.readthedocs.io/en/latest/customization.html
很简单，html_theme = 'sphinx_rtd_theme'改为html_theme = ‘alabaster’
Google Analytics追踪
去谷歌创建新账号和property，拿到这个ID，填到readthedocs后台。
UA-253317179-1 或者 G-K4WP6HMMF7
https://docs.readthedocs.io/en/stable/analytics.html
然后去conf.py和网站admin里填入，chrome源码检查是否生效（可能需要多刷新几次），在手机上访问测试。
Getting Started with Sphinx
用Sphinx来写文档。
rst我不熟，全部改为md格式，配合notebook使用。index.rst这个不能改。
用md没问题，但是toc网站无法识别，还是乖乖用rst吧。
https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
pip install sphinx
cd /Users/zxli/Documents/GitHub/bt3m-multimodal/docs
支持md，notebook，rst三种格式。
# md need this package pip install myst-parser
# notebook need this package pip install nbsphinx
# nb for md pip install myst_nb
make html报错“module 'jinja2.utils' has no attribute 'escape'”
安装老版本包：pip install jinja2==3.0.3
继续报错
Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html
装起来就行了。
本地配置都挺好的，但是上传到云端就报错 “index.rst not found”
添加配置文件Configuration File【至关重要！】
https://docs.readthedocs.io/en/stable/config-file/v2.html
需要copy “.readthedocs.yaml”到本地，但是一定要注意tab格式一定要对，这是Python的规则。
还有conf.py的地址要对，最新版的在source文件夹里，拷贝里的默认在上一层。【搞死我了，最终终于google发现了！！！】
把md、notebook的依赖包放在这里docs/requirements.txt。
添加jupyter notebook
https://docs.readthedocs.io/en/stable/guides/jupyter.html
主要是：
- conf.py里的extensions需要改；
- 其次就是docs/requirements.txt里面的包需要安装；
其他细节
调出header上的导航栏【首页的toc格式】
添加logo
footnote简化
主页添加带图片的Thumbnails gallery
加入getting started页面【安装配置包信息】
加入User Guide页面【详细的notebooks】
加入API页面
加入FAQ页面
加入News/Updates页面
自动生成函数API
优化内容链接
参考：https://github.com/readthedocs/tutorial-template/blob/main/docs/source/usage.rst
注意：
- build文件夹里为生成的网站内容，为缓存，是可以删掉的。
