faircamp/docs

Faircamp Documentation

To generate the docs run the faircamp-docs bin target from the root directory of the repository, passing a single argument – the folder to which the docs should be written.

Take extra care specifying the path, this directory gets wiped and rewritten in the process.

cargo run --bin faircamp-docs -- /path/to/docs/danger/will/be/wiped

Emphasis again: Make sure to run this from the root directory of the repository.

Configuring the build

Set the FAIRCAMP_VERSION environment variable to override the version that is displayed in the build (by default the one currently set in faircamp's root/workspace Cargo.toml file is used).

FAIRCAMP_VERSION=3.0.0~preview cargo run --bin faircamp-docs -- /path/to/docs/danger/will/be/wiped

Set the FAIRCAMP_DOCS_CLEAN_URLS environment variable (e.g. to true) to generate a build of the docs that uses clean urls (i.e. with all relative links in the docs being of the form /foo/ instead of /foo/index.html). Obviously, do not use this option if you plan to use or package the docs for offline usage (clean urls require a server for seamless browsing).

FAIRCAMP_DOCS_CLEAN_URLS=true cargo run --bin faircamp-docs -- /path/to/docs/danger/will/be/wiped

Check internal links/references

For automatically checking integrity of internal cross-links in the docs, including references to anchors on pages, use a tool like https://linkchecker.github.io/linkchecker/index.html (with the AnchorCheck plugin enabled in https://linkchecker.github.io/linkchecker/man/linkcheckerrc.html) on the generated docs.

For instance:

linkchecker [docs-path]/index.html