darktable Lua Documentation

This is the user documentation for the darktable Lua extensions. The content is authored in markdown and rendered to HTML using Hugo and to PDF and ePub using the DITA Open Toolkit.

The auto-built version of the website can be found at https://darktable-org.github.io/luadocs/.

Contributing

Please see https://darktable-org.github.io/dtdocs/special-topics/contributing/ for information about contributing content

Obtaining and Building

Cloning

The theme for the site uses https://gitlab.com/patdavid/hugo-bootstrap-bare as a git submodule. In order to clone this submodule along with the site you just need to add the flag --recurse-submodules to the clone command:

git clone --recurse-submodules https://github.com/darktable-org/dtdocs.git

If you already have the site cloned, but haven't included the submodule before:

git submodule update --init --recursive

Hugo

This site is built with the static site generator Hugo (extended). Currently v0.75.1 extended:

$ ./hugo version
Hugo Static Site Generator v0.73.0/extended windows/amd64 BuildDate: unknown

SASS

If cloning the repo fresh, remember to build the bootstrap assets locally:

$ cd ./themes/hugo-bootstrap-bare/assets/
$ yarn install (or alternatively `npm install`)
$ cd ../../hugo-darktable-docs-theme/assets/
$ yarn install

Updating

If you have the repo cloned but need to update things, it helps to make sure everything is up to date (since we are also using a submodule for the base theme).

As normal, from the project root directory, update things like normal:

git pull

Double check that the submodule is being updated as well:

git submodule update --init --recursive

And finally make sure the assets are built:

cd themes/hugo-bootstrap-bare/assets/
yarn install (or alternatively `npm install`).

This should get things up and running.

Building

You can build the HTML website locally, the production site to deploy to hosting, or the PDF.

Local Website

Building the site to test locally can be done from the root of the repo.

$ hugo server -D --disableFastRender

The site should then be available at http://localhost:1313/dtdocs/

Production Website

Run the hugo command:

hugo

The static files are now available to deploy to a webhost in the public directory. This is currently performed automatically when new changes are pushed to the master branch, via github Actions.

PDF

Ensure you have the weasyprint application installed; this will transform the generated HTML to PDF.

mkdir -p public
hugo server --disableFastRender --config config-pdf.yaml
weasyprint http://localhost:1313/dtdocs/index.html public/darktable_lua_documentation.pdf
pkill hugo

The PDF is available in the public directory.