8. VSCode make html and pdf

8.1. View docs as html

There are a few different ways to view how the documentation will look before pushing it to GitHub and viewing it in RTDs. The first option below displays a preview of the .rst file. The second and third option require the use of Sphinx to build the html output.

8.2. View docs as html in VSCode

  • Install the reStructuredText extension in VSCode, then use the Open Preview to the Side icon at the top right of the window to preview an open .rst file.

8.3. View docs as html

  • Press ctrl + shift + ` to open the VSCode terminal.

  • Make sure that the terminal folder is the docs folder.

  • eg: C:/projects/project-name/docs

  • Build an html version of the docs.

make clean
make html

  • make clean is needed first since Sphinx only rebuilds pages that have changed.

  • Open the index file _build/html/index.html in a web browser to see the docs.

  • The html can also be viewed in the browser using the VSCode terminal.

start chrome _build/html/index.html

  • Add the VSCode extension open in browser to add the command open in default browser to the pop up menu when right clicking the html file in VSCode explorer panel.

8.4. View docs as html using localhost

  • Press ctrl + shift + ` to open the VSCode terminal.

  • Make sure that the terminal folder is the docs folder.

  • eg: C:/projects/project-name/docs

  • Build an html version of the docs using the the VSCode terminal.

make clean
make html

  • Create a local server using the the VSCode terminal.

python -m http.server

start chrome http://localhost:8000/_build/html/

Tip

Sometimes .\ will be needed with make

.\make clean
.\make html

8.5. View docs as pdf

Make the latex build then create the pdf from the .tex file.

8.6. Make latex

  • Press ctrl + shift + ` to open the VSCode terminal.

  • Make sure that the terminal folder is the docs folder.

  • eg: C:/projects/project-name/docs

  • Build a latex version of the docs.

make clean
make latex

  • Change directory to _build/latex

cd _build\latex

  • Create the pdf from the .tex file.

xelatex PC-Using-RTD.tex