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文件夹里为生成的网站内容,为缓存,是可以删掉的。

 

posted @ 2023-01-09 05:03  Life·Intelligence  阅读(136)  评论(0编辑  收藏  举报
TOP