当前位置: 首页 > news >正文

从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系统下&#xf…...

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语言初相识:探索编程之路

&#x1f308;个人主页&#xff1a;聆风吟_ &#x1f525;系列专栏&#xff1a;星计划★C语言、Linux实践室 &#x1f516;少年有梦不应止于心动&#xff0c;更要付诸行动。 文章目录 &#x1f4cb;前言一. ⛳️第一个c语言程序二. ⛳️数据类型2.1 &#x1f514;数据单位2.2 &…...

搜维尔科技:借助 ARVR 的力量缩小现代制造业的技能差距

借助ARVR的力量缩小现代制造业的技能差距 搜维尔科技&#xff1a;Senseglove案例-扩展机器人技术及其VR应用...

数据结构之栈和队列

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

centos安装使用elasticsearch

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

4.7学习总结

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

自定义gitlog格式

git log命令非常强大而好用&#xff0c;在复杂系统的版本管理中扮演着重要的角色&#xff0c;但默认的git log命令显示出的东西实在太丑&#xff0c;不好好打扮一下根本没法见人&#xff0c;打扮好了用alias命令拍个照片&#xff0c;就正式出道了&#xff01; 在使用git查看lo…...

Redission--分布式锁

Redission的锁的好处 Redission分布式锁的底层是setnx和lua脚本(保证原子性) 1.是可重入锁。 2.Redisson 锁支持自动续期功能&#xff0c;这可以帮助我们合理控制分布式锁的有效时长&#xff0c;当业务逻辑执行时间超出了锁的过期时间&#xff0c;锁会自动续期&#xff0c;避免…...

非关系型数据库(缓存数据库)redis的集群

目录 一.群集模式——Cluster 1.原理 2.作用 3.特点 4.工作机制 哈希槽 哈希槽的分配 哈希槽可按照集群主机数平均分配&#xff08;默认分配&#xff09; 根据主机的性能以及功能自定义分配 redis集群的分片 分片 如何找到给定key的分片 优势 二. 搭建Redis群集…...

MySQL:表的约束(上)

文章目录 空属性默认值列描述zerofill主键 本篇总结的是MySQL中关于表的约束部分的内容 空属性 在进行表的创建时&#xff0c;会有两个值&#xff0c;null和not null&#xff0c;而数据库默认的字段基本都是空&#xff0c;但是在实际的开发过程中要保证字段不能为空&#xff…...

树莓派5使用体验

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

代码随想录算法训练营第42天| 背包问题、416. 分割等和子集

01 背包 题目描述&#xff1a;有n件物品和一个最多能背重量为w 的背包。第i件物品的重量是weight[i]&#xff0c;得到的价值是value[i] 。每件物品只能用一次&#xff0c;求解将哪些物品装入背包里物品价值总和最大。 二维dp数组01背包&#xff1a; 确定dp数组以及下标的含义 …...

Node.js安装及环境配置指南

Node.js安装及环境配置指南 一、Node.js的安装 安装Node.js之前&#xff0c;首先需要确保你的电脑已经安装了合适的编译器和开发环境。Node.js是一个开源的、跨平台的JavaScript运行环境&#xff0c;它使得JavaScript可以在服务器端运行。 下载Node.js安装包 访问Node.js的…...

【Java基础】面试题汇总

Java基础面试题1. JVM vs JDK vs JRE 2. 什么是字节码?采用字节码的好处是什么?3. 为什么说 Java 语言“编译与解释并存”&#xff1f;4. AOT 有什么优点&#xff1f;为什么不全部使用 AOT 呢&#xff1f;5. Java 和 C 的区别&#xff1f;6. Java 中的基本数据类型&#xff1…...

数据库事务的超级详细讲解,包括事务特性、事务隔离级别、MVCC(多版本并发控制)

数据库事务&#xff1a; 主要有事务特性&#xff0c;事务的隔离级别&#xff0c;MVCC。 事务特性&#xff1a; 事务&#xff08;Transaction&#xff09;是指作为单个逻辑工作单元执行的一系列操作&#xff0c;这些操作要么全部成功执行&#xff0c;要么全部不执行&#xff…...

鸿蒙Lottie动画-实现控制动画的播放、暂停、倍速播放、播放顺序

介绍 本示例展示了lottie对动画的操作功能。引入Lottie模块&#xff0c;实现控制动画的播放、暂停、倍速播放、播放顺序、播放到指定帧停止或从指定帧开始播放、侦听事件等功能&#xff0c;动画资源路径必须是json格式。 效果预览 使用说明&#xff1a; 进入页面默认开始201…...

C++面试100问与自动驾驶100问

C的学习和面试其实是非常的不友好的&#xff0c;首先C的学习内容非常的多&#xff0c;其次C的面试不单单面试C的知识点&#xff0c;还有它的“七大姑八大姨”&#xff08;计算机网络、数据结构、算法、计算机组成原理、操作系统、编译、xxx的底层实现 and so on&#xff09;。 …...

加速 Redis 操作:掌握管道技术提升性能与效率

Redis 管道技术是一种用于优化 Redis 命令执行效率的机制。在传统的 Redis 操作中&#xff0c;每次向 Redis 服务器发送一个命令&#xff0c;都需要等待命令执行完成并返回结果&#xff0c;这样会导致频繁的网络通信和服务器端的命令执行开销&#xff0c;降低系统的性能和吞吐量…...

深入浅出 -- 系统架构之分布式系统底层的一致性

在分布式领域里&#xff0c;一致性成为了炙手可热的名词&#xff0c;缓存、数据库、消息中间件、文件系统、业务系统……&#xff0c;各类分布式场景中都有它的身影&#xff0c;因此&#xff0c;想要更好的理解分布式系统&#xff0c;必须要理解“一致性”这个概念。 其实关于…...

MFC内存泄露

1、泄露代码示例 void X::SetApplicationBtn() {CMFCRibbonApplicationButton* pBtn GetApplicationButton();// 获取 Ribbon Bar 指针// 创建自定义按钮CCustomRibbonAppButton* pCustomButton new CCustomRibbonAppButton();pCustomButton->SetImage(IDB_BITMAP_Jdp26)…...

生成 Git SSH 证书

&#x1f511; 1. ​​生成 SSH 密钥对​​ 在终端&#xff08;Windows 使用 Git Bash&#xff0c;Mac/Linux 使用 Terminal&#xff09;执行命令&#xff1a; ssh-keygen -t rsa -b 4096 -C "your_emailexample.com" ​​参数说明​​&#xff1a; -t rsa&#x…...

Module Federation 和 Native Federation 的比较

前言 Module Federation 是 Webpack 5 引入的微前端架构方案&#xff0c;允许不同独立构建的应用在运行时动态共享模块。 Native Federation 是 Angular 官方基于 Module Federation 理念实现的专为 Angular 优化的微前端方案。 概念解析 Module Federation (模块联邦) Modul…...

JUC笔记(上)-复习 涉及死锁 volatile synchronized CAS 原子操作

一、上下文切换 即使单核CPU也可以进行多线程执行代码&#xff0c;CPU会给每个线程分配CPU时间片来实现这个机制。时间片非常短&#xff0c;所以CPU会不断地切换线程执行&#xff0c;从而让我们感觉多个线程是同时执行的。时间片一般是十几毫秒(ms)。通过时间片分配算法执行。…...

如何在最短时间内提升打ctf(web)的水平?

刚刚刷完2遍 bugku 的 web 题&#xff0c;前来答题。 每个人对刷题理解是不同&#xff0c;有的人是看了writeup就等于刷了&#xff0c;有的人是收藏了writeup就等于刷了&#xff0c;有的人是跟着writeup做了一遍就等于刷了&#xff0c;还有的人是独立思考做了一遍就等于刷了。…...

【开发技术】.Net使用FFmpeg视频特定帧上绘制内容

目录 一、目的 二、解决方案 2.1 什么是FFmpeg 2.2 FFmpeg主要功能 2.3 使用Xabe.FFmpeg调用FFmpeg功能 2.4 使用 FFmpeg 的 drawbox 滤镜来绘制 ROI 三、总结 一、目的 当前市场上有很多目标检测智能识别的相关算法&#xff0c;当前调用一个医疗行业的AI识别算法后返回…...

学习STC51单片机32(芯片为STC89C52RCRC)OLED显示屏2

每日一言 今天的每一份坚持&#xff0c;都是在为未来积攒底气。 案例&#xff1a;OLED显示一个A 这边观察到一个点&#xff0c;怎么雪花了就是都是乱七八糟的占满了屏幕。。 解释 &#xff1a; 如果代码里信号切换太快&#xff08;比如 SDA 刚变&#xff0c;SCL 立刻变&#…...

在树莓派上添加音频输入设备的几种方法

在树莓派上添加音频输入设备可以通过以下步骤完成&#xff0c;具体方法取决于设备类型&#xff08;如USB麦克风、3.5mm接口麦克风或HDMI音频输入&#xff09;。以下是详细指南&#xff1a; 1. 连接音频输入设备 USB麦克风/声卡&#xff1a;直接插入树莓派的USB接口。3.5mm麦克…...

绕过 Xcode?使用 Appuploader和主流工具实现 iOS 上架自动化

iOS 应用的发布流程一直是开发链路中最“苹果味”的环节&#xff1a;强依赖 Xcode、必须使用 macOS、各种证书和描述文件配置……对很多跨平台开发者来说&#xff0c;这一套流程并不友好。 特别是当你的项目主要在 Windows 或 Linux 下开发&#xff08;例如 Flutter、React Na…...

02.运算符

目录 什么是运算符 算术运算符 1.基本四则运算符 2.增量运算符 3.自增/自减运算符 关系运算符 逻辑运算符 &&&#xff1a;逻辑与 ||&#xff1a;逻辑或 &#xff01;&#xff1a;逻辑非 短路求值 位运算符 按位与&&#xff1a; 按位或 | 按位取反~ …...