Create .documentationrc file to sort project settings

[anthonydillon]

When building documentation each project requires a number of flags to be set. For example:

documentation-builder --base-directory ../vanilla-brochure-theme/docs \
                      --site-root '/en/vanilla-brochure-theme/index' \
                      --output-path 'en/vanilla-brochure-theme' \
                      --template-path template.html \
                      --tag-manager-code 'GTM-K92JCQ'  \
                      --no-link-extensions \
                      --force

This is difficult to type/remember so the command is normally added to a scirpt like ./build-docs. This makes it difficult to modify the flags like changing the source-directory in a one off case.

I propose that the settings can be stored in a .documentationrc file which is committed to the project and is looked up when running documentation-builder. Therefore you only need to run documentation-builder in the project with overriding flags.

[nottrobin]

@anthonydillon and I discussed this offline, but I'll try to capture what was said here for posterity:

TLDR

Providing the ability to store options in a .documentationrc file will definitely be helpful. However, we shouldn't store anything like as many options as @anthonydillon has suggested above. The documentation should be tested by building in the simplest way possible, with the least number of options. And only these basic options should be included in the RC file.

Explanation

Each project should have a set of authoritative documentation in simple Markdown format, so that this documentation can be easily found, read and edited. In its most basic form, hopefully it can be read in plain text format.

Conforming with documentation-builder format

By storing this documentation in a format that documentation-builder is able to parse, we can provide end-users with the ability to not just read the documentation in markdown format, but also to build it into a set of HTML files which can be viewed in the browser, for easier viewing.

Therefore, all that any project should require is that its documentation can be built in the most simple fashion with documentation-builder, as e.g. vanilla-framework already does: https://github.com/vanilla-framework/vanilla-framework#building-documentation-pages

Testing conformance

Building the documentation in this basic fashion (documentation-builder --base-directory docs) is all that is required to ensure that the documentation conforms with the documentation-builder format. Therefore, we should never require that each change to the source documentation be tested with all the possible documentation-builder options - making sure that these options work is the responsibility of documentation-builder itself, not of any project which happens to use it.

Documentation websites are irrellevant

The fact that some websites exist (docs.vanillaframework.io or docs.ubuntu.com) which builds the documentation with specific documentation-builder options to e.g. place media files in the static directory or include a Google Tag Manager code in the built markup is of absolutely no interest or relevance to the source documentation.

Options are useful for local projects

However, the vanilla-framework README does recommend that you build it with a couple of options:

documentation-builder --base-directory docs --output-path docs/build

And it will certainly be a bit of a pain to type these out each time, or to tweak these options for each project you want to test.

So it does make sense to provide these options in an RC file.

[nottrobin]

As a result of the restructure of docs inherent in the new Kubernetes deployment plan, each documentation set is now going to include the infrastructure for its own hosting and packaging.

This means it would make sense for the .documentationrc to be much more complete exactly as described by @anthonydillon above. It could help a lot with canonical/docs.ubuntu.com#88.