从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 服务器发送一个命令,都需要等待命令执行完成并返回结果,这样会导致频繁的网络通信和服务器端的命令执行开销,降低系统的性能和吞吐量…...
深入浅出 -- 系统架构之分布式系统底层的一致性
在分布式领域里,一致性成为了炙手可热的名词,缓存、数据库、消息中间件、文件系统、业务系统……,各类分布式场景中都有它的身影,因此,想要更好的理解分布式系统,必须要理解“一致性”这个概念。 其实关于…...
idea Springboot 电影推荐系统LayUI框架开发协同过滤算法web结构java编程计算机网页
一、源码特点 springboot 电影推荐系统是一套完善的完整信息系统,结合mvc框架和LayUI框架完成本系统springboot dao bean 采用协同过滤算法进行推荐 ,对理解JSP java编程开发语言有帮助系统采用springboot框架(MVC模式开发)&…...
xss【2】
1.xss钓鱼 钓鱼攻击利用页面,fish.php黑客钓鱼获取到账号密码存储的位置 xss进行键盘记录 2.xss常规防范 3.xss验证payload XSS(跨站攻击)_details/open/ontoggle-CSDN博客...
时序分解 | Matlab实现GSWOA-VMD改进鲸鱼优化算法优化变分模态分解时间序列信号分解
时序分解 | Matlab实现GWO-CEEMDAN基于灰狼算法优化CEEMDAN时间序列信号分解 目录 时序分解 | Matlab实现GWO-CEEMDAN基于灰狼算法优化CEEMDAN时间序列信号分解效果一览基本介绍程序设计参考资料 效果一览 基本介绍 Matlab实现GSWOA-VMD改进鲸鱼优化算法优化变分模态分解时间序…...
css- 4
1.浮动 1. 浮动最初用于实现文字环绕效果 2. 现在,浮动是主流的布局方式之一 1.1元素浮动之后的特点 元素浮动之后,称为浮动元素,具有如下特点: 1. 浮动元素脱离文档流 2. 多个浮动的元素会水平排列,一行放不下自动换…...
22.括号生成
题目描述 数字 n 代表生成括号的对数,请你设计一个函数,用于能够生成所有可能的并且 有效的 括号组合。 示例 1: 输入:n 3 输出:[“((()))”,“(()())”,“(())()”,“()(())”,“()()()”] 示例 2: 输入…...
JAVA八股--redis
JAVA八股--redis 如何保证Redis和数据库数据一致性redisson实现的分布式锁的主从一致性Redis脑裂现象及解决方案介绍I/O多路复用模型undo log 和 redo log(没掌握MyISAM 和 InnoDB 有什么区别? 如何保证Redis和数据库数据一致性 关于异步通知中消息队列…...
[图像处理] MFC载入图片并绘制ROI矩形
上一篇: [图像处理] MFC载入图片并进行二值化处理和灰度处理及其效果显示 文章目录 前言完整代码重要代码效果 前言 上一篇实现了MFC通过Picture控件载入图片。 这一篇实现ROI功能的第一部分,在Picture控件中,通过鼠标拖拽画出一个矩形。 完…...
Godot 4 教程《勇者传说》依赖注入 学习笔记(0):环境配置
文章目录 前言相关地址环境配置初始化环境配置文件夹结构代码结构代码运行 资源文件导入像素风格窗口环境设置背景设置,Tileap使用自动TileMap 人物场景动画节点添加站立节点添加移动动画添加 通过依赖注入获取Godot的全局属性项目声明 当前项目逻辑讲解角色下降添加代码位置问…...
强行让Java和Go对比一波[持续更新]
概述 很多Java开发如果想转Golang的话,比较让Java开发蛋疼的第一是语法,第二是一些思想和设计哲学的Gap,所以我这儿强行整理一波Java和Golang的对比,但是由于GO和Java在很多方面都有不同的设计,所以这些对比的项可以更…...
理解七层网络协议
osi体系结构 上三路(管数据) 应用层 通过http等,把传输的格式,数据打包 处理网络应用。直接为端用户服务,提供各类应用过程的接口和用户接口。例如:HTTP、Tenlent、FTP、SMTP、NFS等。基于TCP的FTP、HTTP…...
网站改版 打造企业文化/百度站长工具怎么关闭教程视频
1 含义 HTTP来源地址(referer,或 HTTP referer)是HTTP表头的一个字段,用来表示从哪儿链接到目前的网页,采用的格式是URL。换句话说,借着HTTP来源地址,目前的网页可以检查访客从哪里而来…...
上上海网站设计建设/珠海百度seo
北邮计算机仿真设计报告-学位论文计算机控制仿真课程设计姓名 学院 自动化学院 专业 自动化专业 班级 学号 03) 09) 12) 指导教师2013年7月目录 TOC \o "1-3" \h \z \u HYPERLINK \l "_Toc361403599" 一、引言1 HYPERLINK \l "_Toc361403600" 1.…...
wordpress首页添加幻灯/北京网站排名推广
文章目录一、ZooKeeper概述二、ZooKeeper数据模型1)ZooKeeper数据模型Znode1、引用方式2、Znode结构3、节点类型4、观察2)ZooKeeper中的时间1、Zxid2、版本号3)ZooKeeper节点属性三、ZooKeeper架构四、ZooKeeper中Observer【ZooKeeper伸缩性】…...
wordpress 如何分页/2022年新闻热点摘抄
<url-pattern>/</url-pattern> 会匹配到 /login 这样的路径型url,不会匹配到模式为*.jsp这样的后缀型url。 这种形式不会覆盖任何其它的servlet。它仅仅替换了servlet容器中内建的默认servlet。这种形式通常只用来请求静态资源(CSS/JS/image…...
官方wordpress模板下载/b2b平台推广
另一种选择可能是让您的片段实现View.OnClickListener并覆盖片段中的onClick(View v)。如果您需要让片段与活动通信,只需添加具有所需方法的接口,并让活动实现接口并覆盖其方法。public class FragName extends Fragment implements View.OnClickListene…...
django做的网站源码/舆情监测软件免费版
不要用">>"来从文件中读取空格或回车符,因为该重载运算符从文件中读取字符时,它遇空格或换行就会结束,要读取空格或回车符的话,最好用文件流的成员函数。 当>>运算符遇到空格或回车时,若没有读到任何数据,会跳过空格或回车符,继续…...