docs

SPHINX Documentation Local Build Guide

Windows

Requirements:

• Python
• Make
• Powershell 'Run as Admininstrator'

Steps:

• Verify Python Installation

  PS C:\Users\Administrator> python --version
  Python 3.11.4
  

• Verify Make installation

  PS C:\Users\Administrator> make --version
  GNU Make 3.81
  Copyright (C) 2006  Free Software Foundation, Inc.
  This is free software; see the source for copying conditions.
  There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
  PARTICULAR PURPOSE.
  
  This program built for i386-pc-mingw32
  

• Create a new python virtual environment

  PS C:\Users\Administrator\Downloads> python -m venv docs_env
  

• Activate the Virtual Environment

  PS C:\Users\Administrator\Downloads> .\docs_env\Scripts\Activate.ps1
  

• Navigate to docs directory in trafficcontrol repo and install the requirements

  (docs_env)PS C:\Users\Administrator\Downloads\trafficcontrol\docs> pip install -r source/requirements.txt
  

• Upgrade Sphinx and Sphinx-autobuild

  (docs_env)PS C:\Users\Administrator\Downloads\trafficcontrol\docs> pip install --upgrade sphinx sphinx-autobuild
  

• Build docs files locally with necessary make commands

  (docs_env)PS C:\Users\Administrator\Downloads\trafficcontrol\docs> make html
  

  (docs_env)PS C:\Users\Administrator\Downloads\trafficcontrol\docs> make clean
  

Mac/Linux

Requirements:

• Python
• Make (Usually comes pre-installed)

Steps:

• Create a new python virtual environment

  python -m venv new_rst
  

• Activate the Virtual Environment

  source path_to_your_virtual_env/new_rst/bin/activate
  

• Navigate to docs directory in trafficcontrol repo and install the requirements

  pip install -r requirements.txt
  

• Build docs files locally with necessary make commands

  make html
  

  make clean