Readthedocs+Github搭建文档

环境配置

要求已经具备下列工具:

  • Python
  • pip

本教程是在Windows10上进行搭建的,Linux需要稍作修改

原文链接:Getting Started

  1. 安装Sphinx美化文章
$ pip install sphinx sphinx-autobuild
  1. 在本地创建一个你要保存文档的文件夹,然后进入到该文件夹
$ cd /path/to/project
$ mkdir docs
$ cd docs
  1. 使用sphinx-quickstart进行快速配置
$ sphinx-quickstart
  1. 使用tree查看目录结构(该步骤可以跳过)
  2. 修改 index.rst ,然后运行下面的命令进行预览
$ make html
  1. 打开build文件夹下的html文件,即可预览。

支持Markdown格式

参考:In Markdown

将本地修改提交到远程仓库

首先在根目录下(也就是和build,source等文件夹在同一级目录)建立一个.gitignore文件,其内容如下:

build/
.idea/
*.pyc

然后在本地建立一个仓库,并提交到远程,步骤如下:

  • 第一步:本地建立git仓库

    cd到你的本地项目根目录下,执行git命令
    git init
  • 第二步:将项目的所有文件添加到仓库中
    git add .
    如果想添加某个特定的文件,只需把.换成特定的文件名即可
  • 第三步:将add的文件commit到仓库
    git commit -m "注释语句"
  • 第四步:去github上创建Repository,点击下面的New Organization,拿到创建的仓库的https地址,不会创建可以参考GitHub 实现多人协同提交代码并且权限分组管理
  • 第五步:重点来了,将本地的仓库关联到github上
    git remote add origin github仓库地址
  • 第六步:上传github之前,要先pull一下,执行如下命令:
    git pull origin master

    错误提示 : fatal: refusing to merge unrelated histories

    解决:在进行git pull 时,添加一个可选项(在更高版本的保护机制)
    git pull origin master --allow-unrelated-histories
  • 第七步,也就是最后一步,上传代码到github远程仓库
    git push -u origin master

    执行完后,如果没有异常,等待执行完就上传成功了,中间可能会让你输入Username和Password,你只要输入github的账号和密码就行了

连接Readthedocs和Github

现在,文件已经提交到了你的github仓库,接下来需要把github和Readthedocs连接起来,连接过程分两种情况:

  1. 个人仓库。很简单,在你登录readthedocs时,直接选择sign in with github就可以了。
  2. 多人合作的仓库。需要Webhooks(钩子)才能实现同步,下面着重提一下Webhooks。

首先用github或者用邮箱注册一个Readthedocs账号,然后登录。

然后选择import a project>>手动导入>>填写代码仓库地址等>>下一页

然后就是它自动进行同步了,这是,因为没有webhooks,所以同步不会成功。

接下来,找到project settings>>Integrations>>GitHub incoming webhook你会进入到下图的页面:

将红色框住的地址复制,粘贴到github的Webhooks中。操作过程是:打开代码仓库>>Settings>>Webhooks>>Add webhooks>>Payload URL,如下图:

接下来你就可以向这个仓库添加代码,然后Readthedocs就会有相应的更新。

这样,一个多人协同办公的技术文档就可以搭建起来了。

更改主题 sphinx_rtd_theme

更改source/conf.py:

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

理解书写格式和文件组织方式

原文地址:https://www.cnblogs.com/thethomason/p/9734722.html

时间: 2024-10-24 22:31:06

Readthedocs+Github搭建文档的相关文章

openvpn搭建文档

# openvpn搭建文档 ## 安装相关包文件 ### 安装openssl和lzo包,lzo包用于压缩通讯数据加快传输速度 ``` yum -y install openssl openssl-devel yum -y install lzo ``` ### 安装openvpn和easy-rsa ``` yum -y install openvpn easy-rsa ``` ## 服务器端生成相关文件 ### 修改vars文件 ``` cd /usr/share/easy-rsa/2.0/ v

生产环境轻量级dns服务器dnsmasq搭建文档

dnsmasq搭建文档 一.生产环境域名解析问题 之前生产环境设备较少,是通过维护master(192.168.1.1)设备的hosts文件实现的.每次新增设备后,需要在master的hosts文件中新增ip和主机名,再将master的hosts文件批量拷贝到生产所有已部署设备和新增设备.设备少时维护比较简单,随时设备越来越多,维护起来变得很繁琐,批量拷贝也非常消耗精力. 为了减轻维护成本,和提高维护效率,在生产环境搭建一台dns服务器非常有必要. 进过筛选,dnsmasq这个轻量级的dns服务

环境搭建文档——Windows下的Python3环境搭建

前言 背景介绍: 自己用Python开发了一些安卓性能自动化测试的脚本, 但是想要运行这些脚本的话, 本地需要Python的环境. 测试组的同事基本都没有安装Python环境, 于是乎, 我就想直接在网上找一篇Python环境搭建的文章, 但是没有找到让我觉得简洁又满意的搭建文档,所以我就直接用虚拟机的环境去记录一次Python环境的搭建文档 说明: 此次搭建的是Windows下的Python3的环境, Python2的环境应该也可以参照这篇文章(建议大家使用Python3的环境, Python

GitHub帮助文档阅读说明1——helloWorld

工欲善其事必先利其器 ,都不知道 GitHub到底是什么,还怎么玩?因为总是会读了第一句就忘了下一句,形成不了感觉,所以希望把读GitHub的帮助文档都翻译出来,总是看大段大段的东西,谁都会懵圈的.希望对后来的伙伴能起到一点借鉴的作用,翻译不当之处还望见谅.请回帖,会尽早更新.欢迎讨论交流 https://guides.github.com/activities/hello-world/ 这部分的翻译: GitHub guides GitHub 引导 Hello World 10minute r

github 自学文档 希望可以给初学的人一些帮助

一 .git的安装 windows下面的安装:https://git-for-windows.github.io  从这里下载完全无脑安装. 安装完成后,在开始菜单里找到"Git"->"Git Bash"  表示安装成功. 之后,在命令行输入: $ git config --global user.name "Your Name" $ git config --global user.email "[email protected

cacti监控搭建文档(中文版)

说明:CactiEZ中文版V10.1是基于CentOS6.0系统,整合Cacti等相关软件,重新编译而成的一个操作系统! 优点:省去了复杂烦琐的Cacti配置过程,安装之后即可使用,全部中文化,界面更友好 缺点:CactiEZ是一个完整的操作系统,需要专门一台电脑才能安装使用 监控主机搭建: 一:首先下载cacti镜像.参考链接http://pan.baidu.com/s/1mgIBEo4 密码:sa5o 二:安装.如果是虚拟机安装,请设置磁盘空间大于10G,安装过程基本上一直是默认回车. 三

各种Java项目环境搭建-文档引用汇总记录

springmvc环境搭建 1.如何用Maven创建web项目(具体步骤) 2.springmvc环境搭建,一步一步超简单

代理服务器搭建文档

前言:检测到jayproxy使用的squid作为代理服务器,固我们也使用此软件来搭建代理服务器. 翻墙分析:Squid是很好的代理服务器,但它不能直接翻墙,因为在连接到Squid的过程中,就已经被墙了.所以得把传输的数据先进行加密再传输,这样等于是绕过了防火墙,这里就需要使用Stunnel来传输加密数据. 服务器需求: 1.一台可以正常访问互联网的服务器,代号A(国外的) 2.一台可以正常访问服务器A的国内服务器,代号B 访问过程: 1.用户设置代理指向B服务器的Stunnel服务监听的端口,访

Hadoop集群搭建文档

  环境: Win7系统装虚拟机虚拟机VMware-workstation-full-9.0.0-812388.exe Linux系统Ubuntu12.0.4 JDK                jdk-7u17-linux-i586.tar.gz 搭建步骤: 首先在win系统装虚拟机,执行VMware-workstation-full-9.0.0-812388.exe: 其次需要在虚拟机上装Ubuntu12.0.4: 安装完成Ubuntu12.0.4之后,需要安装JDK,(注意:安装JDK需