My original intention of blogging is to build my own knowledge system systematically. The platform currently used is WeChat official account, CSDN, blog Garden, GitHub Pages and Gitee Pages. Each of them has their own advantages and disadvantages. After sorting out the notes, it is found that these platforms are not very convenient, such as official account, CSDN and blog Garden. It also needs to be edited and republished on the platform, which is troublesome; Although GitHub pages and gitee pages can be published quickly, they are not very convenient in article system management. I hope to sort out my notes like e-books to facilitate search and management. After querying the data, I found ReadtheDocs, a document management tool, which is more in line with my needs. You can use Sphinx to generate documents, GitHub to host documents, and then import them into ReadtheDocs for display. This article records the construction process.
Preparation conditions
1. github account
use github Version management of documents
2. Register the Read the Docs account
Official website address: https://readthedocs.org/
3. Install Python
Sphinx Is a python tool for generating documents, so you need to install the python environment.
Sphinx create document
Sphinx is a Python based document generation project. It started as a tool for generating official Python documents. For more information, please refer to the official website: https://www.sphinx.org.cn/ .
1. Install Sphinx
GitHub address of Sphinx: https://github.com/sphinx-doc/sphinx
pip installing Sphinx
$ pip install -U sphinx
2. Create a document
First clone the remote github warehouse to the local. This warehouse is the warehouse where you want to host documents. If not, create a new one.
After clone arrives locally, create a docs directory in the project root directory, cd enters the docs directory, and execute the following command:
$ sphinx-quickstart Welcome to the Sphinx 4.2.0 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Selected root path: . You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: y The project name will occur in several places in the built documentation. > Project name: Test Development Notes > Author name(s): hiyongz > Project release []: 0.1.0 If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language. > Project language [en]: zh_CN Creating file D:\pythonproj\devtest\source\conf.py. Creating file D:\pythonproj\devtest\source\index.rst. Creating file D:\pythonproj\devtest\Makefile. Creating file D:\pythonproj\devtest\make.bat. Finished: An initial directory structure has been created. You should now populate your master file D:\pythonproj\devtest\source\index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
You can select the default for the above configuration. You can modify the generated conf.py configuration file later.
After setting, the directory structure is as follows:
│ make.bat
│ Makefile
│
├───build
└───source
│ conf.py
│ index.rst
│
├───_static
└───_templates
- build stores compiled files
- source/_static store static files
- source/_templates stores template files
- source/conf.py project configuration file. The above configuration can be modified here
- source/index.rst Homepage
3. Compilation
Compile rst files to generate HTML and related static files:
$ make html Running Sphinx v4.2.0 loading translations [zh_CN]... done making output directory... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: [new config] 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindex done writing additional pages... search done copying static files... done copying extra files... done dumping search index in Chinese (code: zh)... done dumping object inventory... done build succeeded. The HTML pages are in build\html.
The contents of the index.rst file will be compiled into_ build/html directory.
Open_ build\html\index.html file, the following is the rendered HTML page:
The default theme is not good-looking. You can configure other themes.
4. Configure theme
Installing sphinx Read the Docs theme
pip install sphinx_rtd_theme
More topics can be found on the official website https://sphinx-themes.org/ see.
Configure the source/conf.py file:
import sphinx_rtd_theme html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
Recompile:
$ make html
Open_ build\html\index.html file, you can find that the theme configuration is successful.
5. Configure markdown
Sphinx uses the reStructuredText markup language by default. Since you are used to using markdown for document editing, let's configure markdown.
1) Install the recommonmark plug-in
pip install recommonmark
2) Install plug-ins that support markdown tables
pip install sphinx_markdown_tables
The python environment of ReadTheDocs seems to have no sphinx_markdown_tables, the following errors may be reported during construction:
ModuleNotFoundError: No module named 'sphinx_markdown_tables'
The solution is to create a new requirements.txt file in the docs directory and write the following contents:
sphinx-markdown-tables==0.0.15
3) Configure the source/conf.py file
Add:
extensions = ['recommonmark','sphinx_markdown_tables']
Create a markdown file in the source directory and add the makdown file name to source/index.rst
.. toctree::
:maxdepth: 2
:caption: Contents:
windows-shortcuts.md
Recompile
4) Submit upload
Add the docs/build / directory to the. gitignore file. You don't need to upload this directory. Upload:
git add . git commit -m "Submission instructions" git push -u origin master
Associate Read the Docs
Associate Read the Docs so that they can access documents online.
Browser access https://readthedocs.org/ , click my project - > Import a Project:
Select warehouse
Click next
Build version
After the build is complete, click to read the document
Build successful
The online document address is https://devtest-notes.readthedocs.io/.
reference material:
- https://www.sphinx.org.cn/
- https://readthedocs.org/
- https://github.com/readthedocs/readthedocs.org
- https://docs.readthedocs.io/en/stable/tutorial/
- https://www.osgeo.cn/sphinx/usage/markdown.html
- https://www.sphinx-doc.org/zh_CN/master/usage/configuration.html
- https://iridescent.ink/HowToMakeDocs/Basic/reST.html