Readthedocs+github Building Documents

Environment configuration

The following tools are required:

• Python
• Pip

This tutorial is built on WINDOWS10 and Linux needs to be modified slightly.

Original link: Getting Started

1. Installing Sphinx Landscaping Articles

$ pip install sphinx sphinx-autobuild

1. Create a folder locally where you want to save the document, and then go to the folder

$ cd /path/to/project$ mkdir docs$ cd docs

1. Use Sphinx-quickstart for quick configuration

$ sphinx-quickstart

1. Use tree to view the directory structure (this step can be skipped)
2. Modify index.rst , and then run the following command to preview

$ make html

1. Open the HTML file under the Build folder to preview it.

Support Markdown Format

Reference: In Markdown

Committing local modifications to the remote repository

Start by creating a file in the root directory (that is, folders such as Build,source and so on), with the .gitignore following content:

build/.idea/*.pyc

Then build a repository locally and submit it to the remote with the following steps:

• First step: Build a local git repository

  cd到你的本地项目根目录下，执行git命令git init

• Step Two: Add all the files of the project to the warehouse

  git add .如果想添加某个特定的文件，只需把.换成特定的文件名即可

• Step three: Commit the Add file to the repository

  git commit -m "注释语句"

• Fourth step: To create repository on GitHub, click on the New Organizationbelow, get the HTTPS address of the warehouse created, will not be created can refer to GitHub implementation of multi-person collaborative commit code and permission Group management

• Fifth step: Focus on the local warehouse to GitHub

  git remote add origin github仓库地址

• Sixth step: Before uploading GitHub, pull it first and execute the following command:

  git pull origin master

  Error tip: fatal:refusing to merge unrelated histories

  解决：在进行git pull 时，添加一个可选项（在更高版本的保护机制）git pull origin master --allow-unrelated-histories

• Seventh step, the last step, upload the code to GitHub remote repository

  git push -u origin master

  After execution, if there is no exception, wait for the completion of the upload successfully, the middle may let you enter username and password, you just enter GitHub's account and password on the line

Connect Readthedocs and GitHub

Now that the files have been submitted to your GitHub repository, the next step is to connect GitHub with the Readthedocs, which can be divided into two different situations:

1. Personal warehouses. As simple as when you log in to Readthedocs, you can choose sign on with GitHub directly.
2. a multi-person cooperative warehouse . Need Webhooks (hook) to achieve synchronization, the following emphasis on Webhooks.

First register a Readthedocs account with GitHub or email, then log in.

Then select import a project >> 手动导入 >> 填写代码仓库地址等 >> 下一页 .

Then it syncs automatically, which is because there is no webhooks, so synchronization will not succeed.

Next, find project settings Integrations the page that >> >> GitHub incoming webhook you will go to:

Copy the red-framed address and paste it into GitHub's webhooks. The procedure is: Open code warehouse >> Settings >> Webhooks >> Add webhooks >> Payload URL , such as:

Next you can add code to the repository, and then the Readthedocs will be updated accordingly.

In this way, a multi-person work together with the technical documentation can be set up.

Change Theme Sphinx_rtd_theme

Change source/conf.py:

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

Understand writing formats and how documents are organized

• Understanding RST Files

• Understanding Toctree Directives

Readthedocs+github Building Documents