Create a folder where you want to put your project into, and start with sphinx-quickstart in command prompt, and the following the instructions step by step,
Where you want to put your project (root folder)
Whether or not to separate build folder from source folder
for this one I answer y instead of the default value
Fill Project name, author name and project release
C:\Pyrad\SphinxReStructuredText\sphinxproject>sphinx-quickstart Welcome to the Sphinx 4.5.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: pyradnotes > Author name(s): Pyrad > Project release []:
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]:
Finished: An initial directory structure has been created.
You should now populate your master file C:\Pyrad\SphinxReStructuredText\sphinxproject\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.
Build html files
Now you can run make <builder> to build docs by leveraging a Makefile which was generated just now.
Here <builder> could be html, latex or linkcheck.
For example, if I want to build html style webpage, I run, make html, and an index.html will be created in .\build\html\index.html, open this file to preview.
C:\Pyrad\SphinxReStructuredText\sphinxproject>make html Running Sphinx v4.5.0 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 English (code: en)... done dumping object inventory... done build succeeded.
The HTML pages are in build\html.
Here now this project folder we have the following directories and files
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
C:\Pyrad\SphinxReStructuredText\sphinxproject>tree /f Folder PATH listing for volume Windows Volume serial number is 2E24-EB6F C:. │ make.bat │ Makefile │ ├─build ---> I skip this folder as all files in it are generated by Makefile each time │ └─source │ conf.py │ index.rst │ ├─_static └─_templates
Instead of using windows command prompt, you could open the project folder in Visual Studio Code, and run make html in built-in terminal (PowerShell), and open .\build\html\index.html directly.
1 2 3
PS C:\Pyrad\SphinxReStructuredText\sphinxproject> make html PS C:\Pyrad\SphinxReStructuredText\sphinxproject> .\build\html\index.html PS C:\Pyrad\SphinxReStructuredText\sphinxproject>
Also you can install extension reStructedText in Visual Studio Code, which can help you with syntax highlighting when editing .rst files, also it can preview .rst files.