[Solved] How do I build the API docs website from source?

[Blockhead]

Many users make use of, and sometimes even prefer**, the API docs published at api.luanti.org, compared to the raw Markdown.

Today on the Matrix channel it was asked how the content on the website form can be compiled from source. Thankfully, this is all present within the main repository of Luanti's source code, where a lot of documentation lives, not just the Lua API. Inside doc/mkdocs we have two files: requirements.txt, which is a file for the Python package manager, pip, to read; and build.sh, which will use mkdocs to build the html.

Even if you are on a system like Linux or BSD, you will not want to try to install the packages in requirements.txt via your operating system package manager. Debian doesn't have some of the requirements, and it has one of the biggest package archives. Instead, you will want to set up a virtual environment for pip to install the right versions of the packages in requirements.txt*. Open a terminal in luanti/docs/mkdocs[/url] and create a virtual environment:

Code: Select all

$ python3 -m venv $PWD

Next, install the requirements locally:

Code: Select all

$ bin/pip install -r requirements.txt

Now call build.sh to build the docs, including the local virtual environment bin directory in your path:

Code: Select all

$ PATH=$PATH:$PWD/bin ./build.sh

That hopefully succeeded. You may now be wondering where the built files in HTML format are. The clue is in the last line of build.sh:

Code: Select all

mkdocs build --site-dir ../../public

In there you will find index.html to open with your browser. However, this is not as ideal as deploying it to a web server. Most browsers now have a security model where pages are not trusted to load other resources from localhost, so your search will not work. Also since there is no web server redirection, clicking on categories will land you in a directory listing inside of Firefox instead of going to index.html for that section. There are two solutions to this, both of which involve using mkdocs more directly yourself.

The first is to run the local development web server when viewing the docs:

Code: Select all

luanti/doc/mkdocs$ PATH=$PATH:$PWD/bin mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.39 seconds
INFO     -  [02:23:00] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [02:23:00] Serving on http://127.0.0.1:8000/
INFO     -  [02:23:11] Browser connected: http://127.0.0.1:8000/
INFO     -  [02:23:17] Browser connected: http://127.0.0.1:8000/search.html?q=entity

The other is to deploy it to your own GitHub Pages instance. For that, I have not looked into it in depth, but it is fairly straightforward with mkdocs gh-deploy.

For more info, you should look at mkdocs' own User Guide.

Footnotes

**What do I prefer personally? Personally, I prefer to Ctrl-F/grep through the contents of the markdown file, and when I send links I link to particular versions, so that the line numbers do not go out of sync.

*hypothetically, you could just install them to your home directory, but this doesn't seem very clean to me.