SiFli Documentation Toolbox for Sphinx

Usage

After installing the package, run sf-build-docs to build the document in the document root folder (in the same folder as version.json). The document source files need to be structured as below

.
|
├── source
│   ├── _static
│   │   
│   ├── _templates
|   |
│   ├── assets
|   |
│   ├── en
│   │   ├── conf.py
│   │   └── index.md
│   └── zh_CN
│       ├── conf.py
│       └── index.md
├── .gitignore
|
└── version.json

You can also get a template document by cloning https://github.com/opensifli/sifli-doc-template/.

sf-build-docs命令行参数：

• --help: 查看命令行参数说明
• --lang: 指定文档语言，缺省为中文
• --version: 指定文档版本号，缺省为latest
• --pdf: 生成PDF文档，缺省为生成HTML文档, Windows平台不支持PDF文档编译
• --clean: 清空编译，如果编译不同格式的文档需要选择清空编译，比如编译完PDF格式的文档想编译HTML，需要选择清空编译
• --cores: 指定并行编译使用的内核数量，缺省为8个

安装

Python版本使用3.12，pip版本使用24.0，高版本的python和pip（比如3.15）可能因为对wheel文件名检查更严格而安装失败。

The latest version could be found:

• wheel
• source

Old version could be found:

• v0.1.5
• v0.1.4

自定义配置

在文档项目的conf.py里可以使用如下变量对文档进行配置

• doc_id: 文档编号, 比如 UM5202、RPT5202
• chip: 芯片型号，比如 SF32LB52x
• doc_name: 文档名称，比如“用户手册”、“芯片规格书”、“功耗测试报告”等
• pdf_url_enabled: HTML文档是否需要放置PDF文档链接，True: 有链接
• doc_dir: 文档路径，比如在线文档的链接是https://docs.sifli.com/projects/rpt5202_sf32lb52x-low-power-measurement-report/latest/zh_CN/index.html，则dor_dir设置 为rpt5202_sf32lb52x-low-power-measurement-report

PDF文件名规则

如果同时定义了doc_id、chip和doc_name三个变量，那么PDF文档名以{doc_id}_{chip}_{doc_name}_{version}.pdf格式命名，其中version为版本号， 否则以{project}_{version}.pdf格式命名，其中project也是在conf.py中定义的项目名称