Add embedded documentation (user guide)

User guide is embedded into the application now. From the updated README:

README.MD

There is a user guide embedded into the application (it is linked to from the navbar). It uses Docusaurus, which is a static site generator for documentation: https://docusaurus.io/docs. The folder ./ldvspec/documentation contains a docusaurus project that contains markdown (.MD) which make up the user guide.

Workflow:

• You write your documentation efforts in the markdown files found in the ./ldvspec/documentation/docs folder
• When local: from ./ldvspec/documentation/, run the command npm build-ldvspec-local. The static static will be generated into the folder ../lofardata/static/documentation
• CI/CD: the static site will be generated into Django from within the Dockerfile automatically

Caveat

There is a catch when embedding a single page application into a classic web app such as Django. A single page application uses routing on the frontend (e.g., /docs/user-guide will cause it render some html). This works fine, until you refresh (i.e., F5) the page or nagivate to the link by entering it in your browser. These actions will actually cause your browser to request that url (e.g., /docs/user-guide) from Django, which of course does not exist. This is a common problem. Django is not adequately equipped to deal with this issue, because its static file serving library is very simple. Instead, we solve it with Traefik when it is deployed.

The docker compose files for deploying to dev and prod contain path replace middleware. Whenever a user navigates to any subpath of the static generated documentation, Traefik will return the correct index.html file.

Relevant lines of code in the docker compose:

- "traefik.http.routers.ldv-specification.middlewares=ldv-spec-docs-replace"
- "traefik.http.middlewares.ldv-spec-docs-replace.replacepathregex.regex=/static/documentation/docs/(.*)"
- "traefik.http.middlewares.ldv-spec-docs-replace.replacepathregex.replacement=/static/documentation/index.html"

This means that locally, you need to navigate to /static/documentation/index.html to check the deployed documentation (don't use the navbar link and don't press F5).

Embed in Confluence

You can embed the documentation page in Confluence using an iFrame macro. Because the documentation is now only a generated frontend application, it will appear embedded and fully functional in Confluence. See also:

https://support.astron.nl/confluence/display/SDCP/User+Guide