Technical Documentation for Data Analytics & AI using MkDocs Material

Table of Contents

• Getting Started
  • Option 1: Viewing the Deployed Documentation (Recommended)
  • Option 2: Serving Locally
  • Option 3: Building the Documentation
• Install Dependencies
  • Anaconda (Recommended)
  • Poetry
  • venv

Getting Started

We provide several options for you to access our documentation based on your needs. You may choose one or more of the following options based on your requirements.

Option 1: Viewing the Deployed Documentation (Recommended)

Directly head to the deployed documentation at this link to view the documentation. This option requires no installation of setting up and is great for non-technical stakeholders or project managers.

Note

For the subsequent options, we recommend viewing the section Install Dependencies first.

Option 2: Serving Locally

Run the following command to view the documentation in localhost:

mkdcos serve

You should see the following output:

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.69 seconds
INFO    -  [10:27:13] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [10:27:13] Serving on http://127.0.0.1:8000/

Option 3: Building the Documentation

Alternatively, you may build the documentation with the following command:

mkdocs build

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /path/to/site
INFO    -  Documentation built in 1.13 seconds

You should now see a folder in your root directory called site. This folder can be shared with internal members or across teams for portability. However, it lacks for in terms of user experience.

Install Dependencies

Anaconda (Recommended)

You can download the Anaconda Distribution for your respective operating system here. You may also find out how to get started with Anaconda Distribution here. To verfiy your installation, you can head to the Command Line Interface (CLI) and run the following command:

conda list

You should see a list of packages installed in your active environment and their versions displayed. For more information, refer here.

---

Once set up, create a virtual environment using conda and install dependencies:

# Create a virtual environment
conda create -n <VENV_NAME> python=<PYTHON_VERSION> -y
conda activate <VENV_NAME>

# Install dependencies
pip install -r requirements.txt

Poetry

Refer to the documentation here (recommended) on how to install Poetry based on your operating system.

Important

For Mac users, if encountering issues with poetry command not found, add export PATH="$HOME/.local/bin:$PATH" in your .zshrc file in your home folder and run source ~/.zshrc.

---

First create a virtual environment by running the following commands:

poetry shell

Tip

If you see the following error; The currently activated Python version 3.11.7 is not supported by the project (^3.12). Trying to find and use a compatible version., run:

poetry env use 3.12.3  # Python version used in the project

To install the defined dependencies for your project, just run the install command. The install command reads the pyproject.toml file from the current project, resolves the dependencies, and installs them.

poetry install

If there is a poetry.lock file in the current directory, it will use the exact versions from there instead of resolving them. This ensures that everyone using the library will get the same versions of the dependencies.

If there is no poetry.lock file, Poetry will create one after dependency resolution.

Tip

It is best practice to commit the poetry.lock to version control for more reproducible builds. For more information, refer here.

---

venv

You can use Python's native virtual environment venv to setup the project

# Create a virtual environment
python3 -m venv <VENV_NAME>

You can then activate the environment and install the dependencies using the following commands -

For UNIX-based systems (macOS / Linux):

# Activate virtual environment
source <VENV_NAME>/bin/activate

# Install dependencies
pip install -r requirements.txt

For Windows:

# Activate virtual environment
.\<VENV_NAME>\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Tip

If you're using Python's native virtual environment venv, it is best practice to name your virtual environment venv.