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. Install the reStructuredText extension 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. Build html

8.3.1. From Project folder

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

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

  • eg: C:/projects/project-name

  • Build an html version of the docs in the html folder within the _build folder inside the docs folder.

sphinx-build -b html docs docs/_build/html

8.3.2. From Project docs folder

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

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

  • 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.

  • On Windows, especially in PowerShell, the .\ prefix simply means β€œrun a program that’s in the current directory.”

8.3.3. Build showing errors From Project docs folder

  • Build an html version of the docs.

sphinx-build -b html -W docs/ docs/_build/html

8.4. View docs as html

  • Get the full file path to the file: \docs\_build\html\index.html and paste it into a browser.

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

start chrome C:\Users\<<path details>>\docs\_build\html\index.html

  • file:/// can be used for clarity.

start chrome file:///C:\Users\<<path details>>\docs\_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.5. View docs as pdf

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

8.5.1. From Project folder

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

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

  • eg: C:/projects/project-name

  • Build a latex version of the docs in the latex folder within the _build folder inside the docs folder.

Run in sequence
sphinx-build -b latex docs docs/_build/latex

cd docs/_build/latex

xelatex PC-Using-RTD.tex

8.5.2. From Project docs folder

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

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

  • 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

  • Run the xelatex command a second time to ensure that all references are updated, especially the table of contents.

xelatex PC-Using-RTD.tex

  • Open the pdf file in the Adobe reader or other pdf viewer.

start PC-Using-RTD.pdf