How to test a github repo mkdocs built files locally on Mac OS X?

Question

There's a GitHub repo I like to make changes to its docs. It uses readthedocs to host and mkdocs for the theme.

I am using macOS Mojave.

I found this https://docs.readthedocs.io/en/latest/install.html installation guide to install readthedocs. But I don't see how I can test the built files after I change the mkdocs.yml file of the repo I want to make changes to.

So how do I test the built files for readthedocs when I make changes to the mkdocs.yml locally in macOS X?

I don't mind using docker if that's necessary.

Answer 1

My mental model of the problem is wrong. ReadTheDocs is simply a service that uses a documentation generator (either sphinx or mkdocs) and hosts the output files generated.

To run mkdocs locally, simply:

1. fork the repo
2. clone the fork locally
3. setup a suitable virtual environment (since textX is a python library and so is mkdocs)
4. install the suitable required libraries stated in requirements.txt or requirements_dev.txt depending on the repo
5. run mkdocs serve

The mkdocs will run locally at 127.0.0.1:8000 for you to test the generated html files. To make changes to the mkdocs config, go to the mkdocs.yml