003. Documentation
Feature: #700
Authors: Roel Fauconnier
Status: Accepted
Overview / Problem Statement
Currently the documentation is not very well structured, and content is hard to discover. There is no search except for the built-in GitHub code search. Some of the documentation is spread out across different files.
We want to bring the documentation up-to-date and make it more discoverable.
Proposed solution
-
Use GitHub Pages. GitHub has a "Pages" functionality which allows you to publish a static website to a predefined URL:
https://projectname.github.io
. It can be published from a branch and/or folder. The folders are limited to/
or/docs
. The best practice seems to be to create a detached branch or git subtree calledgh-pages
which contains only the static website in a/docs
folder. -
Use DocFX static site generator. DocFX is an open source tool provided by Microsoft that allows you to generate a static website based on a set of markdown files. Additionally, it can build documentation for a codebase based on the "triple slash" comments (
///
) in .NET code.
It usesyaml
files to provide structure to the documentation. There is no built-in support in GitHub, but there are already some GitHub Actions available to help automate the publishing of docs. However, we will not use the code documentation feature of DocFX, since the code does not represent an API. -
Create a detached branch to keep all docs, called
docs/main
. This keeps history out of the main code repository, and allows for changes to the documentation without triggering any tag, version or CI. -
Create a detached branch to keep static site, called
gh-pages
. This allows for a place where the docs can be published from. -
Versioning: the tool mike is used for managing the versions.
-
Two different workflows will manage the deployment:
- CI for each push to
docs/main
will automatically deploy version calleddev
- Manual workflow with parameter for
version
will deploy that version, set it to latest and additionally tag the repo withdocs@<version>
- CI for each push to
Open Questions
- [x] Can multiple branches be locked in GitHub? E.g. ideally
docs/main
will be locked and can only be updated through a PR. YES - it is possible to add rules to different branches.
Alternatives Considered
-
Structurize the current folders Bring more structure to the current documentation folders, and use GitHub "markdown-preview" feature. The docs can be searched via GitHub search function. This also means adding additional links from each document to other documents to make things more discoverable.
-
Use Jekyll static site generator Jekyll is the default option that Github provides to generate a static website. There are Github Actions available to help you build and publish the static website. Jekyll requires you to add specific
yaml
snippets to your documentation to be able to build a static site. Also, it is not fully supported on Windows right now. -
Use a different repository for the docs While this is a solution for some OSS repositories, it is overkill for this one. Additionally, it may be hard to open a new repository within the Azure organization.
here is a code sample
example code | |
---|---|
1 2 3 4 5 6 7 |
|
Created: 2021-11-10