Repo Setup#

Make Docs#

In your porjects repository make a folder called docs

cd wfrt-demo/
mkdir docs

Now head into the docs/ folder

cd docs/
We are now going to run sphinx-quickstart inside the docs folder.

  • This will ask you a few questions

    1. Either, you use a directory _build within the root path, or you separate source and build directories within the root path.

    2. Project name:

    3. Author name(s):

    4. Project release []:

    5. Project language [en]:

Important

Please answer yes to the first question by typing y than enter. You must say yes to this question for the rest of this quick start guide to function correctly. Answer the remaining questions however you would like.

Run Sphinx#

Lets run sphinx-quickstart by:

sphinx-quickstart

Here is an exmaple code block of each question youll be asked:

Welcome to the Sphinx 3.2.1 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: Sphinx Quickstart Guide
> Author name(s): Christopher Rodell
> 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]:

Creating file /Users/rodell/test/docs/source/conf.py.
Creating file /Users/rodell/test/docs/source/index.rst.
Creating file /Users/rodell/test/docs/Makefile.
Creating file /Users/rodell/test/docs/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /Users/rodell/test/docs/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.

This is what your docs folder will look like if you followed the instruction above.

docs
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

We will now see a some files along with a source and build folder

  • The source folder is the source directory that sphinx uses to build your website.

    • This is where you will be working most of the time

    • conf.py is the configuration script sphinx uses to build the website. We will discuss this in detail later

    • index.rst is the master document to serve as a welcome page, and the root of the website. We will also, discuss this in detail later

  • The build folder is the directory where sphinx will place your website’s content.

    • You dont go here

Sneaky Tricks#

Now we will do two sneaky (yet simple) tricks to make your life much easier.

In the docs/ directory add the following two files.

First, we will add a .nojekyll file to the docs directory

touch .nojekyll
Second let’s add an index.html file that contains a simple meta tag

  • The meta tage will redirect GitHub Pages to your build folder where your websites main index.html lives.

  • I like doing this as you can keep everything within your soruce folder.

touch index.html

copy the following meta tag

<meta http-equiv="refresh" content="0; url=./build/html/index.html" />

and past into index.html

vi index.html
## past meta tage and save

Horray we are making head way! Lets build a website!!!