Building the Website¶
For developers who want to contribute to the website/documentation of libigl. The website is now hosted in its own repository separate from the main libigl repository. You can edit directly pages of the website and create an associated pull requests on github. For more substantial changes, you may want to preview your changes to the website before committing them. The instructions bellow explain how to preview or deploy the website on github.
- Install mkdocs and the material theme
pip3 install -U --user mkdocs mkdocs-material
pipenvto install the dependencies:
pip3 install -U --user pipenv pipenv install requests pipenv shell
- Preview the website locally (in the root folder of the libigl project):
python3 -m mkdocs serve
- Build the website to generate the html locally (optional):
python3 -m mkdocs build
- Deploy the website directly to github (will overwrite the gh-pages branch
of the remote repository):
python3 -m mkdocs gh-deploy
gh-deploy script will overwrite the content of the
gh-pages in the
remote repository. Be sure of what you are doing before pushing new
content with this command.
- Be careful to not have any
<>characters in your email in your
.gitconfig, otherwise the
gh-deployscript will fail.
- Dead links can be checked using the
LinkChecker tool. Run the
website locally, then run LinkChecker on it:
The reason we are using
python -m mkdocs serve instead of
directly is because we are using local extensions for mkdocs. Those extensions
are located in the
scripts/ folder of libigl. Running
mkdocs as a module
adds the current directory to the
PYTHONPATH, allowing us to load those
extensions without installing them on the system or in a virtualenv.
- Building the website with a recent version of mkdocs/Python-Markdown will not work. The problem is documented in libigl.github.io#8. Please let us know you are able to help.
- We are also working on setting up a proper python environment for building the website using conda/virtualenv. Right now it should work on Linux, but some problems may exist on macOS/Windows. We will update the documentation accordingly once this is resolved.