Use ReadtheDocs to host documents

This is the 20th day of my participation in the August Text Challenge.More challenges in August

WangScaler: A writer with heart.

Declaration: uneducated, if there is a mistake, kindly correct.

ReadtheDocs is used for many technical documents, such as Python documents, tornado documents, etc. It’s not pretty, but it’s good enough for technical posts.

Install Python

Using ReadtheDocs requires a PYTHon3 environment because Sphinx is based on Python3. So let’s start by installing the Python environment. If you have a Python environment, you can skip this step and go straight to installing Sphinx.

1. Download Python

Download it from the Python website. It may be slow. Just wait for a while. Select Download to Download the installation package.

Depending on your environment, I downloaded the latest 64-bit version of Windows installation package here.

2, installation,

Add Python 3.8 to PATH Automatically adds python paths to environment variables. You automatically configure the Python environment on your computer so that you can use Python anywhere in the world.

It indicates that the installation is successful, so whether our computer has the Python environment in the end, the next verification.

3, validation,

Win+R Open CMD and type Python.

We’ve seen the python version information, congratulations, and now we’re ready to talk.

Install Sphinx

Sphinx is a powerful document generator with many powerful features for writing technical documentation. Sphinx was originally used to generate official Python documentation, but as the tool has improved, more and more high-profile projects are using it to generate documentation.

1. Install Sphinx

pip install sphinx sphinx-autobuild sphinx_rtd_theme
Copy the code

2. The initialization

Under the window:

d:
cd /wangscaler/
sphinx-quickstar
Copy the code

Linux under

Create a document root directory
mkdir -p /usr/local/wangscaler/
cd /usr/local/wangscaler/
You can enter the default configuration to write
sphinx-quickstart
Copy the code

Here’s what I filled in, and the rest is basically the default:

> Separate source and build directories (y/n) [n]:y
> Project name: WangScaler
> Author name(s): WangScaler
> Project version []: 0.2
> Project release [1.0]: 0.2.2
> Project language [en]: zh_CN
Copy the code

3. Install the software tree. View the directory tree structure.

windows

tree
Copy the code

linux

yum install tree
tree -C .
Copy the code

Support markdown writing and theme switching

Recommonmark is a plugin that supports Markdown, while Sphinx-Markdown-tables is the theme. Since the default theme is ugly, we can use this theme to optimize our interface.

1. Install the plug-in

pip install recommonmark
pip install sphinx-markdown-tables
Copy the code

2. Modify the configuration

Then change conf.py. My configuration looks like this:

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
import shlex
sys.path.insert(0, os.path.abspath('. '))

import recommonmark
from recommonmark.transform import AutoStructify
# -- Project information -----------------------------------------------------
source_suffix = ['.rst'.'.md']

master_doc = 'index'

project = 'Interface'
copyright = '2021, WangScaler'
author = 'WangScaler'
version = recommonmark.__version__
# The full version, including alpha/beta/rc tags
release = recommonmark.__version__


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc'.'sphinx.ext.napoleon'.'sphinx.ext.mathjax'.'recommonmark'.'sphinx_markdown_tables',]# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'zh_CN'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build']
default_role = None
pygments_style = 'sphinx'
todo_include_todos = False
# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
htmlhelp_basename = 'Recommonmarkdoc'
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',

# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
#'preamble': '',

# Latex figure (float) alignment
#'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
  (master_doc, 'Recommonmark.tex', u'Recommonmark Documentation',
   u'Lu Zero, Eric Holscher, and contributors'.'manual'),
]
man_pages = [
    (master_doc, 'recommonmark', u'Recommonmark Documentation',
     [author], 1)
]
texinfo_documents = [
  (master_doc, 'Recommonmark', u'Recommonmark Documentation',
   author, 'Recommonmark'.'One line description of project.'.'Miscellaneous'),]# At the bottom of conf.py
# def setup(app):
# app.add_config_value('recommonmark_config', {
# #'url_resolver': lambda url: github_doc_root + url,
# 'auto_toc_tree_section': 'Contents',
# 'enable_math': False,
# 'enable_inline_math': False,
# 'enable_eval_rst': True,
# 'enable_auto_doc_ref': True,
# }, True)
# app.add_transform(AutoStructify)

Copy the code

3. Write a document

Now that the framework is almost complete, let’s write our first article.

Create a new hello. RST in the source directory as follows:

# My New Learning ## MongoCopy the code

4. Modify the index. RST file

This file is the directory of our blog to which we can add new posts when we have them.

. Test documentation master file, created by sphinx-quickstart on Mon Jul 20 09:49:03 2020. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Interface Document! = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =). Toctree :: maxDepth: 2: Caption: hello Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`Copy the code

5. Compile the file

Execute make HTML in the root directory to compile our files into web pages. Our job is done. Get ready to visit our blog.

6. Preview the effect

Go to the build/ HTML directory and open index.html in your browser

7, static web deployment

Compiled web pages that can be accessed through nginx deployment can be easily accessed by referring to my previous nginx common operations by placing static web pages in a specified location.

4. Problems encountered

1. The picture is not displayed

Solution:

1. Images are loaded using graph bed
2. Use relative paths, such as /images/a.jpg

Note: the path is/not \ the second option is not feasible

2. The table is not displayed

pip install sphinx-markdown-tables
Copy the code

Change it in the conf.py file

extensions = [
    'sphinx.ext.autodoc'.'sphinx.ext.napoleon'.'sphinx.ext.mathjax'.'recommonmark'.'sphinx_markdown_tables'.# This sentence supports markdown tables
]
Copy the code

Come all come, click “like” and then go!

Follow WangScaler and wish you a promotion, a raise and no bucket!