Skip to content

ds-group-innovation/SphinxDOC

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

78 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

关于文档📌

Documentation Status GitHub GitHub issues GitHub last commit All Contributors Netlify Status

本文档描述了一个伟大组织的传奇(不接受反驳~😊(●'◡'●))

本文档基于伟大的Sphinx项目构建(你没想错,伟大的Python的文档就是用它整的),我们还使用了同样伟大的GitHub和ReadtheDocs进行文档自动构建和托管,文档写作所使用的文本标记(Markup)语言为reStructuredText + Markdown。文档使用了不怎么帅的主题sphinx-rtd-theme

如果各位路过的大佬发现文档有写的不对或者可以改进的地方,欢迎向我们提issue和pull request,谢谢啦

如何参与文档的编辑与维护✍

由于本文档基于Sphinx,而这玩意是个Python项目,所以你需要安装Python的相关环境,你不需要会Python就可编辑和构建文档。文档的主要依赖(Python Packages)如下:

sphinx

sphinx-rtd-theme

recommonmark

注意

  • 如果你之间已经clone过本项目,请先拉取更新再编辑

如果你直接clone了本项目的代码仓库,可以使用git pull进行拉取更新,如果你先fork到了自己的仓库而且clone到你本地的是你自己的仓库,那么可以编辑本地项目的.git/config(如果你使用的是windows系统,.git目录会默认隐藏),增加如下配置

[remote "origin"]
	url = https://github.com/seven-innovation-base/SpinxDOC
	fetch = +refs/heads/*:refs/remotes/origin/*

然后使用git pull拉取更新

一、环境配置

在开始前请先fork一下这个项目,再clone到本地(clone的是你名下的同名仓库)

我们建议你使用virtualenv+pip的方式管理本文档构建所依赖的环境,如果你想使用pipenv或者单纯用pip也行,方法如下:

git clone https://github.com/your_username/SphinxDOC

pip + virtualenv

# 1、转到项目目录
cd SphinxDOC
# 2、安装virtualenv
pip install virtualenv
# 3、为本项目创建虚拟环境
virtualenv venv
# 4、激活虚拟环境
cd venv/Scripts
activate
cd ../..
# 5、安装依赖
pip install -r requiremen.txt
# 6、清除之前构建好的文件
make clean
# 7、试下构建文档
make html
# 8、构建好的静态文件再_build目录下,点击index.html进行预览

pipenv

pip install pipenv

pipenv install  # 创建虚拟环境,安装依赖

pipenv shell  # 激活虚拟环境

./make clean

./make html  # 构建文档,在_build/html/index.html 预览

二、文档编辑与构建

环境搭建好后,就可以编辑*.rst*.md文件进行文档编辑了,如果你想新增rstmd文件或优化文档结构,请先阅读Sphinx中文文档的文档结构的定义章节

md的格式有限,可以考虑用rst,可以一开始可以用Markdown写然后用pandoc将Markdown格式转换为restructText继续编辑。

如果你已经编辑完成,请先使用make clean清楚之前构建好的静态文件,然后使用make html构建新文档,然后进行效果预览(构建好文件位于**_build/html**目录中),如果没啥毛病就push到GitHub并向我们提交pull request

拓展阅读

感谢以下小伙伴的付出 ✨


GrayHat

💻

Mr.Ye

💻

许可证📑

Apache-2.0 © Seven Innovation base, see the license for more details.

Releases

No releases published

Packages

No packages published

Languages

  • HTML 72.8%
  • JavaScript 21.0%
  • CSS 4.9%
  • Python 0.9%
  • Batchfile 0.2%
  • Makefile 0.2%