Edit a technote on your own computer¶

For most writers, the best way to edit a technote is on a computer you control and can install software on. This might be your own laptop, or a computer account in the cloud like the Rubin Science Platform or GitHub Codespaces.

If you don’t already have a technote repository set up, Start a new technote first.

Set up¶

Clone the repository¶

First clone the GitHub repository containing your technote. In a terminal, run git clone https://github.com/repo.

The URL for the repository is provided by the Slack bot when you created the technote.

Initialize the Python environment¶

In a terminal, from the root of the repository, run:

make init

This installs two Python packages: tox and pre-commit. Both of these tools create their own isolated Python environments to actually run the document builder and linter in. Because of that, you don’t need to rely on a specific Rubin Conda environment to build technotes.

Important

Tox and pre-commit generally use the Python that they were installed with. Documenteer requires Python 3.11 or later. To check what version of Python you have, run:

python --version

Build the technote’s web page¶

In a terminal, from the root of the repository, run:

make html

This will build the technote’s web page and put it in the _build/html directory. On a Mac, you can open the page in your browser:

open _build/html/index.html

Under the hood, make html invokes tox and its html environment to build the technote in an isolated Python environment.

Running linters¶

Technote projects are configured to use linters to check for common issues.

To run the linters on-demand, run:

make lint

That command runs both the Pre-commit hooks and the link checker. If you ran make init, the Pre-commit hooks will also run automatically before every Git commit.

Resetting your environment¶

Both the Python environment and the web site build are cached. You might want to reset those caches if the website is not building properly, or if you suspect that the Python environment is out of date (for example, a new version of Documenteer is available). To delete the caches, run:

make clean

Then run make html again to rebuild the website in a fresh environment.

Tip

You can be more selective about what you clean. If you only want to delete the website cache, but keep all the installed Python packages in the Python environment, run:

rm -rf _build