Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: add info on building now that we have insider material theme

...

  1. Install Python 3.

  2. Create a virtual environment for the project:

    • python3 -m venv env
      
  3. Activate the virtual environment:

    • source
      source env/bin/activate
      
    • An (env) now appears at the beginning of your prompt.
  4. Install all the required dependencies in this virtual environment.
    We use two requirements files because we have an insider (sponsored) version of material design theme and only readthedocs preview and build can use it. So you will use the non insider version for local preview.
    The requirements.txt is for the common dependencies, the requirements-mkdocs-material.txt is for installing the mkdocs material theme.
    Run both commands:

    • pip install -r CI/requirements.txt
    • pip install -r CI/requirements-mkdocs-material.txt
  5. Run the following command in the project directory:

    • mkdocs serve
      
  6. In the output of this command, follow the link displayed on the line that looks like the following:

    • [
      190206
      I 190206 18:48:47 server:298] Serving on http://127.0.0.1:8000
      
    • In this case, go to http://127.0.0.1:8000. You can let this server run while you work on the documentation. It updates the local website automatically when you save changes in your Markdown files.

  7. Deactivate the virtual environment if you work on another Python project, by running deactivate. You can preview the same documentation site again starting from step 3 and skipping step 4, until you update Python.

...