Lagrange Docs

This repository contains the source files used to generate the Lagrange documentation website. The generated documentation is available at the following URL:

https://opensource.adobe.com/lagrange-docs/

The documentation is rebuilt by GitHub Actions every time a new commit is pushed to docs branch.

Editing

How to edit

Markdown files, except those generated automatically by Doxygen, can be edited directly through the GitHub website or locally after cloning the repository.

If you want to preview the resulting html page, follow the steps below on how to build the documentation locally.

Theme

The documentation uses the mkdocs-material theme. The theme comes with some extensions, e.g. Admonition. Use Admonition for things like notes, warnings, caveats, examples, etc.

Images

For now images and other media are stored in subfolders in docs/

Building locally

1. Clone the docs branch

The gh-pages branch is reserved for the static html pages. It is advised to only clone the docs branch (the default branch), rather than doing a full clone of the repository:

git clone git@github.com:adobe/lagrange-docs.git --single-branch

2. Setup virtual environment with pixi

Install pixi on your machine to manage the Python environment for this project. Once installed, you have two options:

1. Run pixi shell to enter a shell with the virtual environment created by pixi.
2. Prefix Python commands with pixi run ... to execute a given command in the project's virtual environment.

To avoid any error, we prefix commands in our guide with pixi run .... But feel free to use whichever method you prefer.

3. Generate doxygen + changelog

pixi run generate.py <PATH_TO_LAGRANGE_ROOT>

Note: This will populate the following:

• docs/ref/: html files generated by Doxygen

4. Preview static website

The following will run a local server at 127.0.0.1:8000

pixi run mkdocs serve

Alternatively, use pixi run mkdocs build to generate files into site folder

Deploy

🚨 For reference only!

Note: This is for reference only, GitHub Actions does this automatically.

pixi run mkdocs gh-deploy -b gh-pages

will push to gh-pages branch automatically, which will update the website.

Contributing

Contributions are welcomed! Read the Contributing Guide for more information.

Licensing

The documentation and code snippets on this repository/website are licensed under the CC0 1.0 Universal License. See LICENSE for more information.