从0到1搭建文档库——sphinx + git + read the docs
sphinx + git + read the docs
目录
一、sphinx
1 sphinx的安装
2 本地构建文件框架
1)创建基本框架(生成index.rst ;conf.py)
conf.py默认内容
index.rst默认内容
2)生成页面(Windows系统下)
参考资料
3 编辑说明
1)图片:相对路径
2)文档编辑(官方)
3)页面主题:conf.py中配置
4 多语言支持
参考资料
二、git
1 git使用配置
2 本地推送远程仓库
3 github页面操作
4 git项目拉取
5 git本地提交到新分支
三、read the docs
1 导入时的项目名称设置
2 导入的项目要求
3 项目多版本管理
1) latest:默认分支(可在【管理】中配置)
2) 其他版本和github上的branch/release tag对应编辑
4 文档自动更新的关联
5 离线格式下载
四、小结
1 三者关系
2 文档更新过程
注意
一、sphinx
1 sphinx的安装
先安装Python3环境
Download Python | Python.org
cmd中输入python显示内容即安装成功
再安装sphinx环境
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx
2 本地构建文件框架
1)创建基本框架(生成index.rst ;conf.py)
创建一个空文件夹,输入
sphinx-quickstart
根据提示输入内容
sphinx-quickstart后的文件夹结构
.
├── build
├── make.bat
├── Makefile
└── source├── conf.py├── index.rst├── _static└── _templates
conf.py默认内容
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-informationproject = 'structrucshow'
copyright = '2024, test'
author = 'test'
release = 'v1.0'# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configurationextensions = []templates_path = ['_templates']
exclude_patterns = []language = 'zh_cn'# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-outputhtml_theme = 'alabaster'
html_static_path = ['_static']
index.rst默认内容
.. structrucshow documentation master file, created bysphinx-quickstart on Sun Apr 7 10:38:11 2024.You can adapt this file completely to your liking, but it should at leastcontain the root `toctree` directive.Welcome to structrucshow's documentation!
=========================================.. toctree:::maxdepth: 2:caption: Contents:Indices and tables
==================* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
2)生成页面(Windows系统下)
.\make html
然后点击build/html文件夹下打开index.html浏览页面;
或者
sphinx-autobuild source build/html
点击端口浏览,调整的时候页面会实变化,建议使用这个命令,方便实时查看变化。
参考资料
Sphinx+gitee+Read the Docs搭建在线文档系统 - 知乎
使用ReadtheDocs托管文档 - 知乎
3 编辑说明
1)图片:相对路径
2)文档编辑(官方)
reStructuredText 简介 — Sphinx 使用手册
3)页面主题:conf.py中配置
一般用这个主题:
html_theme = 'sphinx_rtd_theme'
其他主题可以看官方文档
Read the Docs Sample — Read the Docs
4 多语言支持
小结:无法自动翻译,需要根据中文人工手动输入英文内容,然后进行转化(生成一个新的项目)。新项目导入到read the docs(注意设置语言),然后将翻译后的项目配置为原语言项目的子项目,在【翻译】中设置。
参考文档:【Open-Source】Sphinx+Read the Docs的多语言版本文档实现 - 知乎
关键语句(cr↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑)
先向docs/source/conf.py文件添加:
# multi-language docs
language = 'en'
locale_dirs = ['../locales/'] # path is example but recommended.
gettext_compact = False # optional.
gettext_uuid = True # optional.
# 先切到docs目录下
cd docs# 从./source/conf.py中读取文档设置,并调用从写好的rst或md的原文文档中在./build/gettext生成所有文档文件对应的.pot文件
sphinx-build -b gettext ./source build/gettext# 在docs目录下生成目标翻译语言的目录(示例目标翻译语言为zh_CN)
# 这条指令会在docs/locales的目录下生成po文件
# 后续需要在po文件中填入对应的翻译内容
sphinx-intl update -p ./build/gettext -l zh_CN# 翻译内容补充完成后,从写有中文翻译的.po文件和./source/conf.py中的设置来build中文文档,
# 生成的文档会在docs/build/html/zh_CN目录下
sphinx-build -b html -D language=zh_CN ./source/ build/html/zh_CN
将对应的翻译内容填入双引号内
参考资料
Sphinx + Read the Docs 从懵逼到入门 - 知乎
官网:reStructuredText 简介 — Sphinx 使用手册
多语言支持(官网的介绍文档):
国际化 — Sphinx documentation
Localization and Internationalization — Read the Docs user documentation
How to manage translations for Sphinx projects — Read the Docs user documentation
二、git
1 git使用配置
GitHub创建项目的流程_github创建项目步骤-CSDN博客
使用Git将本地文件夹同步至github_git 某些文件同步到新文件-CSDN博客
关键:第一次用git bash需要设置SSH免密,创建public key
2 本地推送远程仓库
git initgit add .git commit -m "描述你的提交"git push origin 分支名
本地项目首次关联git仓库需要提供ssh: git remote add origin git@githuhb.com:XXXXXXX/XXXX.git
参考资料:如何从 GitHub 上创建/克隆一个仓库、进行修改、提交并上传回 GitHub 新手保姆级教程 - 知乎
git拉取项目、提交代码简单教程_git拉取代码-CSDN博客
3 github页面操作
github上创建分支并合并到master_github分支合并到主干-CSDN博客
4 git项目拉取
创建空文件夹
git clone+项目地址
(如果用的https://xxx 链接报错,可尝试使用项目的ssh地址)
cd 项目名称
(进入项目)
git branch
(查看当前分支)
git checkout [branch name]
(切换到新的分支)
git checkout -b 分支名
(创建并切换到新分支)
git branch -D 分支名
(删除本地分支)
参考资料:git创建新分支,并将本地代码提交到新分支上_建立新的本地分支-CSDN博客
5 git本地提交到新分支
git checkout -b [branch name] (
创建分支的同时切换到该分支上)
git add .
git commit -m "add my code to new branchB"
git push origin [branch name]
三、read the docs
1 导入时的项目名称设置
The name of the project. It has to be unique across all the service, so it is better if you prepend your username, for example {username}-rtd-tutorial
.
2 导入的项目要求
必须要有.readthedocs.yaml文件
【示例】
项目层级结构示意图:
.
├── .git
├── .gitignore
├── .readthedocs.yaml
├── requirements.txt
├── images
└── docs├── build├── index.rst├── make.bat├── Makefile└── source6 ├── _static├── _templates├── conf.py└── index.rst
.readthedocs.yaml文件内容:
version: "2"build:os: "ubuntu-22.04"tools:python: "3.10"python:install:- requirements: ./requirements.txtsphinx:configuration: docs/source/conf.py
requirements.txt文件内容
sphinx==7.1.2
sphinx-rtd-theme==1.3.0rc1
build文件不用同步到git仓库,.gitignore中内容
docs/build/
参考资料:Configuration file overview — Read the Docs user documentation
3 项目多版本管理
1) latest:默认分支(可在【管理】中配置)
2) 其他版本和github上的branch/release tag对应
4 文档自动更新的关联
在项目管理中勾选后,git有更新,read the docs会同步重新构建,构建完成后页面变更【大概几分钟延迟】
5 离线格式下载
在.yaml文件中补充
# Optionally build your docs in additional formats such as PDF and ePub
formats:- pdf- epub
参考资料:
Configuration file reference — Read the Docs user documentation
四、小结
1 三者关系
latest默认对应master
read the docs的版本名称可以是分支名称,也可以是release的tag名称
2 文档更新过程
1)当有版本更新时,原先最新的版本release,tag命名vx.x,在项目-版本中激活vx.x
2)创建分支编辑更新
3)分支浏览效果是否合适
4)合适后把新的分支内容合并到master,版本管理中关闭该分支版本
【示例】
一开始只有latest(默认对应master,master永远是最新的),有新版本时:
-
master 分支 release v0.1,项目-版本——激活v0.1
-
修改内容后,发布为branch v0.2,查看内容是否OK
-
OK后合并到master(latest更新),项目-版本——隐藏 branch v0.2 版本
-
当v0.3推出时,master分支 release v0.2,项目-版本——激活v0.2
-
……
注意
避免二者(release tag和branch name)命名重复
如果都是v1.0,read the docs会自动命名为v1.0_a
但是在前端页面都是显示v1.0,所以要避免二者(release tag和branch name)命名重复
相关文章:

从0到1搭建文档库——sphinx + git + read the docs
sphinx git read the docs 目录 一、sphinx 1 sphinx的安装 2 本地构建文件框架 1)创建基本框架(生成index.rst ;conf.py) conf.py默认内容 index.rst默认内容 2)生成页面(Windows系统下…...
EasyExcel 校验后导入
引入pom <dependency><groupId>com.alibaba</groupId><artifactId>easyexcel</artifactId><version>3.3.3</version></dependency>触发校验类 import com.baomidou.mybatisplus.extension.api.R; import lombok.experimental…...

【星计划★C语言】c语言初相识:探索编程之路
🌈个人主页:聆风吟_ 🔥系列专栏:星计划★C语言、Linux实践室 🔖少年有梦不应止于心动,更要付诸行动。 文章目录 📋前言一. ⛳️第一个c语言程序二. ⛳️数据类型2.1 🔔数据单位2.2 &…...
搜维尔科技:借助 ARVR 的力量缩小现代制造业的技能差距
借助ARVR的力量缩小现代制造业的技能差距 搜维尔科技:Senseglove案例-扩展机器人技术及其VR应用...

数据结构之栈和队列
1.前言 大家好久不见,这段时间由于忙去了。就没有即使维护我的博客,先给大家赔个不是。 我们还是规矩不乱,先赞后看~ 今天讲的内容是数据结构中非常重要的一个部分:栈和队列。它在今后的学习中也会再次出现(c&#…...

centos安装使用elasticsearch
1.首先可以在 Elasticsearch 官网 Download Elasticsearch | Elastic 下载安装包 2. 在指定的位置(我的是/opt/zhong/)解压安装包 tar -zxvf elasticsearch-7.12.1-linux-x86_64.tar.gz 3.启动es-这种方式启动会将日志全部打印在当前页面,一旦使用 ctrlc退出就会导…...

4.7学习总结
java学习 一.Stream流 (一.)概念: Stream将要处理的元素集合看作一种流,在流的过程中,借助Stream API对流中的元素进行操作,比如:筛选、排序、聚合等。Stream流是对集合(Collection)对象功能的增强&…...

自定义gitlog格式
git log命令非常强大而好用,在复杂系统的版本管理中扮演着重要的角色,但默认的git log命令显示出的东西实在太丑,不好好打扮一下根本没法见人,打扮好了用alias命令拍个照片,就正式出道了! 在使用git查看lo…...
Redission--分布式锁
Redission的锁的好处 Redission分布式锁的底层是setnx和lua脚本(保证原子性) 1.是可重入锁。 2.Redisson 锁支持自动续期功能,这可以帮助我们合理控制分布式锁的有效时长,当业务逻辑执行时间超出了锁的过期时间,锁会自动续期,避免…...

非关系型数据库(缓存数据库)redis的集群
目录 一.群集模式——Cluster 1.原理 2.作用 3.特点 4.工作机制 哈希槽 哈希槽的分配 哈希槽可按照集群主机数平均分配(默认分配) 根据主机的性能以及功能自定义分配 redis集群的分片 分片 如何找到给定key的分片 优势 二. 搭建Redis群集…...
MySQL:表的约束(上)
文章目录 空属性默认值列描述zerofill主键 本篇总结的是MySQL中关于表的约束部分的内容 空属性 在进行表的创建时,会有两个值,null和not null,而数据库默认的字段基本都是空,但是在实际的开发过程中要保证字段不能为空ÿ…...

树莓派5使用体验
原文地址:树莓派5使用体验 - Pleasure的博客 下面是正文内容: 前言 好久没有关于教程方面的博文了,由于最近打算入门嵌入式系统,所以就去购入了树莓派5开发板 树莓派5是2023年10月23日正式发售的,过去的时间不算太远吧…...

代码随想录算法训练营第42天| 背包问题、416. 分割等和子集
01 背包 题目描述:有n件物品和一个最多能背重量为w 的背包。第i件物品的重量是weight[i],得到的价值是value[i] 。每件物品只能用一次,求解将哪些物品装入背包里物品价值总和最大。 二维dp数组01背包: 确定dp数组以及下标的含义 …...
Node.js安装及环境配置指南
Node.js安装及环境配置指南 一、Node.js的安装 安装Node.js之前,首先需要确保你的电脑已经安装了合适的编译器和开发环境。Node.js是一个开源的、跨平台的JavaScript运行环境,它使得JavaScript可以在服务器端运行。 下载Node.js安装包 访问Node.js的…...

【Java基础】面试题汇总
Java基础面试题1. JVM vs JDK vs JRE 2. 什么是字节码?采用字节码的好处是什么?3. 为什么说 Java 语言“编译与解释并存”?4. AOT 有什么优点?为什么不全部使用 AOT 呢?5. Java 和 C 的区别?6. Java 中的基本数据类型࿱…...
数据库事务的超级详细讲解,包括事务特性、事务隔离级别、MVCC(多版本并发控制)
数据库事务: 主要有事务特性,事务的隔离级别,MVCC。 事务特性: 事务(Transaction)是指作为单个逻辑工作单元执行的一系列操作,这些操作要么全部成功执行,要么全部不执行ÿ…...

鸿蒙Lottie动画-实现控制动画的播放、暂停、倍速播放、播放顺序
介绍 本示例展示了lottie对动画的操作功能。引入Lottie模块,实现控制动画的播放、暂停、倍速播放、播放顺序、播放到指定帧停止或从指定帧开始播放、侦听事件等功能,动画资源路径必须是json格式。 效果预览 使用说明: 进入页面默认开始201…...
C++面试100问与自动驾驶100问
C的学习和面试其实是非常的不友好的,首先C的学习内容非常的多,其次C的面试不单单面试C的知识点,还有它的“七大姑八大姨”(计算机网络、数据结构、算法、计算机组成原理、操作系统、编译、xxx的底层实现 and so on)。 …...
加速 Redis 操作:掌握管道技术提升性能与效率
Redis 管道技术是一种用于优化 Redis 命令执行效率的机制。在传统的 Redis 操作中,每次向 Redis 服务器发送一个命令,都需要等待命令执行完成并返回结果,这样会导致频繁的网络通信和服务器端的命令执行开销,降低系统的性能和吞吐量…...

深入浅出 -- 系统架构之分布式系统底层的一致性
在分布式领域里,一致性成为了炙手可热的名词,缓存、数据库、消息中间件、文件系统、业务系统……,各类分布式场景中都有它的身影,因此,想要更好的理解分布式系统,必须要理解“一致性”这个概念。 其实关于…...
基于算法竞赛的c++编程(28)结构体的进阶应用
结构体的嵌套与复杂数据组织 在C中,结构体可以嵌套使用,形成更复杂的数据结构。例如,可以通过嵌套结构体描述多层级数据关系: struct Address {string city;string street;int zipCode; };struct Employee {string name;int id;…...
Vim 调用外部命令学习笔记
Vim 外部命令集成完全指南 文章目录 Vim 外部命令集成完全指南核心概念理解命令语法解析语法对比 常用外部命令详解文本排序与去重文本筛选与搜索高级 grep 搜索技巧文本替换与编辑字符处理高级文本处理编程语言处理其他实用命令 范围操作示例指定行范围处理复合命令示例 实用技…...

Lombok 的 @Data 注解失效,未生成 getter/setter 方法引发的HTTP 406 错误
HTTP 状态码 406 (Not Acceptable) 和 500 (Internal Server Error) 是两类完全不同的错误,它们的含义、原因和解决方法都有显著区别。以下是详细对比: 1. HTTP 406 (Not Acceptable) 含义: 客户端请求的内容类型与服务器支持的内容类型不匹…...
k8s从入门到放弃之Ingress七层负载
k8s从入门到放弃之Ingress七层负载 在Kubernetes(简称K8s)中,Ingress是一个API对象,它允许你定义如何从集群外部访问集群内部的服务。Ingress可以提供负载均衡、SSL终结和基于名称的虚拟主机等功能。通过Ingress,你可…...

YSYX学习记录(八)
C语言,练习0: 先创建一个文件夹,我用的是物理机: 安装build-essential 练习1: 我注释掉了 #include <stdio.h> 出现下面错误 在你的文本编辑器中打开ex1文件,随机修改或删除一部分,之后…...

高频面试之3Zookeeper
高频面试之3Zookeeper 文章目录 高频面试之3Zookeeper3.1 常用命令3.2 选举机制3.3 Zookeeper符合法则中哪两个?3.4 Zookeeper脑裂3.5 Zookeeper用来干嘛了 3.1 常用命令 ls、get、create、delete、deleteall3.2 选举机制 半数机制(过半机制࿰…...
多模态商品数据接口:融合图像、语音与文字的下一代商品详情体验
一、多模态商品数据接口的技术架构 (一)多模态数据融合引擎 跨模态语义对齐 通过Transformer架构实现图像、语音、文字的语义关联。例如,当用户上传一张“蓝色连衣裙”的图片时,接口可自动提取图像中的颜色(RGB值&…...
oracle与MySQL数据库之间数据同步的技术要点
Oracle与MySQL数据库之间的数据同步是一个涉及多个技术要点的复杂任务。由于Oracle和MySQL的架构差异,它们的数据同步要求既要保持数据的准确性和一致性,又要处理好性能问题。以下是一些主要的技术要点: 数据结构差异 数据类型差异ÿ…...
三体问题详解
从物理学角度,三体问题之所以不稳定,是因为三个天体在万有引力作用下相互作用,形成一个非线性耦合系统。我们可以从牛顿经典力学出发,列出具体的运动方程,并说明为何这个系统本质上是混沌的,无法得到一般解…...
拉力测试cuda pytorch 把 4070显卡拉满
import torch import timedef stress_test_gpu(matrix_size16384, duration300):"""对GPU进行压力测试,通过持续的矩阵乘法来最大化GPU利用率参数:matrix_size: 矩阵维度大小,增大可提高计算复杂度duration: 测试持续时间(秒&…...