How to build the HTML page?

[elsevers]

Apologies for a very rookie question, but... how do I build this website locally with Sphinx? (And should we have a doc with instructions on this?)

Here are my details:

1. I installed Sphinx (conda install sphinx gave me Sphinx v4.4.0)
2. Inside the base folder, I ran make html on the command line and received the error Could not import extension myst_parser
3. I tried to install myst_parser, but condo doesn't have it on its main channel. I do see that there is a myst-parser in condo-forge here. I want to hit the pause button and check in before I go too far along installing all of these packages. Is this the path I should be taking? (Installing myst-parser)

[npetersen2]

Check out: https://github.com/Severson-Group/docs.amdc.dev#local-development

You'll need to install the packages listed in requirements.txt. Then, the website should build with no issues with make html.

As with most development, this is easiest to do in a Linux-based environment (I use WSL on my Windows 10 laptop). However, you could probably make it work using Python via conda.

Also consider checking out the other make options, there are some cool ones! (E.g., build docs into single PDF, verify all links are valid, etc)

[npetersen2]

Example

Building the website from scratch using a clean WSL install, Ubuntu 20.04:

I upgraded my WSL install since I last worked on the docs, so I just went through and got them building from scratch:

1. Install WSL on Windows 10

2. Open up a terminal to your new linux install

3. Update the packages:

$ sudo apt update
$ sudo apt upgrade

4. Install dev tools: (git, make, Python tools)

$ sudo apt install git make python3-pip python3-virtualenv

5. Clone the repo:

$ git clone git@github.com:Severson-Group/docs.amdc.dev.git
$ cd docs.amdc.dev/

6. Create a virtual environment and activate it

$ virtualenv .venv
$ source .venv/bin/activate

7. Install all dependencies (into the virtual env):

$ pip install -r requirements.txt

8. Build the website

$ make clean
$ make html

9. Open the local website docs in your browser: build/html/index.html

10. When you are done, deactivate your venv

$ deactivate

[elsevers]

Nice, thanks! I'll have to try WSL sometime. I was successful with doing this in Python via conda.

I was able to conda install -c conda-forge every dependency except sphinx-last-updated-by-git (this package did not seem to reside in any conda channel and so I resorted to a pip install).