Split single word document into several markup files

[PhilippSalvisberg]

Currently the Trivadis PL/SQL & SQL Coding Guidelines are maintained in a single Microsoft Word document. This is not optimal. For example:

• Changes cannot be easily tracked within a version control system (at least not without additional tooling).
• Multi-user support is limited, it is difficult to ensure that no changes are lost when merging.
• Keeping track of changes after adapting the guidelines for an application/project is difficult (identifying relevant changes and merging them).
• There is no HTML target format. This could simplify linking to chapters/rules from other documents.

The idea is to split the current document into markup files, which may be processed by Jekyll to produce static HTML files and also a PDF file similar to the current one.

This is just a "reformatting" task. It is not the idea to change the content in the first step. As long as this issue is not implemented fully in a satisfactory way, the Word document ist still the master and might be evolved further.

As an inspiration look into the MvvmCross GitHub repository. They generate the documentation with Jekyll including also some JavaScript for search capabilities. See the result.

[PhilippSalvisberg]

The mkdocs project looks good. See the generated website.

The built-in themes support an unlimited number of navigation levels (levels in the menu hierarchy). See https://github.com/mkdocs/mkdocs/issues/1140. This would simplify the initial migration.

There are other 3rd party themes. See https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes. I favour the https://github.com/squidfunk/mkdocs-material theme. See some generated web sites using this theme:

• https://squidfunk.github.io/mkdocs-material/
• https://doc.serenytics.com/
• http://biggis-project.eu/biggis-docs/
• https://docs.vapor.cloud/
• https://docs.longan-labs.cc/
• https://docs.floydhub.com/
• https://aqueduct.io/docs/
• https://docs.pybossa.com/
• https://concoursetutorial.com/
• https://docs.abinit.org/
• https://oracle.github.io/oracle-db-mle/
• https://www.eclipse.org/openj9/docs/

These examples show that an unlimited number navigation levels are supported by Material for MkDocs.

[PhilippSalvisberg]

The following projects could be relevant for this issue as well:

• to create version specific GitHub pages

  • https://github.com/jimporter/mike, example http://jimporter.github.io/bfg9000/latest/

• to generate PDF from mkdocs

  • https://github.com/jgrassler/mkdocs-pandoc
  • https://github.com/Fiware/tools.Md2pdf