Table of Contents
Objective: Create a simple page in Sphinx using RST.
Unfortunately, MobaExterm text editor does not work with Cyrillic. It only accepts ASCII. Here are some options for modifying the content file.
nanoin the terminal.
Create the files using your favorite text editor, then drop and drag them to the file browser in MobaExterm (easiest).
Be sure to navigate to the project folder before uploading them.
Upload them using an FTP client.
Here are a few things to note when working with Sphinx
Our Sphinx build includes the
sphinx_autobuildextension, which detects when a file has changed and then automatically processes the changes.
The HTML files from the build process reside in folder _build.
Do not modify files in this folder. These files are built dynamically.
Sometimes, deleted files reside in the folder. Remove the folder to trigger a rebuild using
rm -r _build
Sphinx converts .rst files to .html files.
The default page is
index.rst, which is what you see when you view the page in the browser.
Sphinx is very particular about syntax. One space will alter the output.
Use the resources in Sphinx and Read the Docs Resources.
Use the Online Sphinx editor to help you get started with RST.
These instructions will get you started.
Create a new
.rstfile. (We’ll use
example.rstfor these instructions.)
Add a heading to the file. See Sphinx’s reStructuredText primer for other heading levels.
*************** This is an H1 *************** Here is some text for file example.rst. This is an H2 heading ====================== Here is content under heading two.
Add additional content using the samples from the Sphinx and Read the Docs guides.
.. toctree:: :maxdepth: 2 :caption: Contents: example This text will show after the table of contents.
Sphinx will look for
example.rstand then add the file to the table of contents.
Sometimes you need to rebuild the HTML files to clear old documents or perform a manual build to view the errors and warnings.
You can trigger a build event by executing
Run this command to build the directory and display errors and warnings.
# docker exec <container_name> <command> docker exec sphinx-server make html
# docker-compose exec <service_name> <command> docker-compose exec sphinx make html
Notice the warning message:
checking consistency... /web/example.rst: WARNING: document isn't included in any toctree
root@vps298933:~/sphinx-server# docker-compose exec sphinx make html Running Sphinx v1.8.5 loading translations [ru]... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 2 source files that are out of date updating environment: 2 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... /web/example.rst: WARNING: document is not included in any toctree done preparing documents... done writing output... [100%] index generating indices... genindex writing additional pages... search copying static files... done copying extra files... done dumping search index in Russian (code: ru) ... done dumping object inventory... done build succeeded, 1 warning. The HTML pages are in _build/html. root@vps298933:~/sphinx-server#