Set up your writing environment

Local development of documentation for Amperity is done on your workstation and requires some configuration.

Requirements

• Python 3.9

• Sphinx 7.3.7

• docutils 0.20

A text editor.

EditPad Pro is recommended for PCs and TextMate is recommended for macOS. You may use your preferred text editor as long as it supports the following:

1. Line wrapping

2. Does not automatically remove spaces at the end of strings.

3. Does not use tabs instead of spaces

Pull the Amperity docs repo

Download the https://github.com/amperity/amperity-docs GitHub repo using GitHub Desktop.

Create Python virtual environment

Run the following commands to create a Python virtual environment.

1. $ cd documents/github/amperity-docs

2. $ python3 -m venv .venv

3. $ source .venv/bin/activate

4. (.venv) $ python3 -m pip install sphinx

5. (.venv) $ sphinx-build --version

   Returns something like:

   “sphinx-build 9.1.0”

Note

(.venv) is not part of the command you should run. This just means “From the Python virtual environment, run the command after $.”

Install dependencies

In the same virtual environment, run the following commands to install theme and a collection of plugins required by theme.

1. $.venv pip install shibuya

2. $.venv pip install sphinx-togglebutton

3. $.venv pip install sphinx_sitemap

4. $.venv pip install sphinxcontrib-mermaid

5. $.venv pip install sphinxcontrib-video

6. $.venv pip install sphinxcontrib-youtube

7. $.venv pip install sphinx-copybutton

8. $.venv pip install sphinx_design

9. $.venv pip install sphinx-new-tab-link

Install requirements

In the same virtual environment, run the following commands:

1. $.venv /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. $.venv brew install python

3. $.venv pip3 install -r requirements.txt

4. $.venv brew install serve

Build the docs

Open a new command shell window, and then run the following commands.

1. $ cd documents/github/amperity-docs

2. $ source .venv/bin/activate

3. $ make

   This builds all of the docs and place the output in the /build directory within the amperity-docs repo.

Clean out the docs build directory

Run the following command: make clean. This removes all output in the /build directory.

View the docs in localhost

Open a new command shell window, and then run the following commands.

1. $ cd documents/github/amperity-docs

2. $ make serve

   This starts a local server for the contents of the /build directory.

3. Open a browser and enter the following URL: http://localhost:8080/.

Set up your Python virtual environment

To set up your local authoring environment:

	Choose your favorite text editor. On a Mac, TextMate is recommended. Important On a Mac, please do not use the built-in TextEdit application to make changes to files in the documentation repo. Its behavior is inconsistent, sometimes unreliable, and can introduce unwanted formatting behaviors and build outcomes.
	Install GitHub Desktop (recommended) or use your preferred tool of choice for interacting with GitHub repos.
	Install Serve, which enables viewing the docs in localhost. On a Mac, use Homebrew: $ brew install serve
	Pull down the docs repo. Use GitHub Desktop to clone the docs repo, using https://github.com/amperity/amperity-docs as the URL value. Tip Put the docs repo into the same location on your local machine as your Amperity apps repo. For example: /documents/github/amperity-docs.
	Open a terminal and cd to the folder containing the docs repo. For example: $ cd documents/github/
	Create a python virtual environment in the repository by running: $ python3 -m venv amperity-docs
	Enter the virtual environment and install the requirements by running: $ cd amperity-docs && source /bin/activate \ && pip install -r requirements.txt
	Run make. This builds the documentation locally on your machine. Note If you get an error similar to “make: sphinx-build: No such file or directory” verify that your $PATH variable is updated to match the location on your machine into which Homebrew or Pip installed Sphinx. Run make serve, and then open http://localhost:8080/ to view the documenation.