Skip to content
GitLab
Projects Groups Snippets
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in / Register
  • P purr-data
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 362
    • Issues 362
    • List
    • Boards
    • Service Desk
    • Milestones
  • Merge requests 49
    • Merge requests 49
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
  • Deployments
    • Deployments
    • Environments
    • Releases
  • Monitor
    • Monitor
    • Incidents
  • Analytics
    • Analytics
    • Value stream
    • CI/CD
    • Repository
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • Jonathan Wilkes
  • purr-data
  • Merge requests
  • !835

Add document generation for ReadMe.html and Welcome.html

  • Review changes

  • Download
  • Email patches
  • Plain diff
Merged Albert Gräf requested to merge aggraef/purr-data:gendoc into master Aug 11, 2022
  • Overview 26
  • Commits 8
  • Pipelines 9
  • Changes 11

These two are now generated from Markdown source, using awk for preprocessing (macro substitution and selection of OS-dependent sections) and pandoc for formatting. A nice-looking GH-style-alike style sheet is also included. All this stuff including the Markdown source can be found in packages/gendoc.

This replaces the jumble of echo commands in the packages/Makefile which was hardly maintainable and produced subpar results. The content of the ReadMe document was outdated as well, so I updated it.

The main advantages are that it is now much easier to edit these documents (simply edit the Markdown source in gendoc/ReadMe.md and gendoc/Welcome.md), replacement of version numbers and OS-dependent information is automatically performed by the awk script, and the resulting html documents produced with pandoc look much better.

I consider this important, since these documents (especially ReadMe.html) are pretty much the first bits of Purr Data related documentation the user sees when installing the package, on Mac and Windows at least where they are prominently featured during the installation. If ReadMe.html then looks like some webpage from the 1990s, with information that is hopelessly outdated, that doesn't make for a great onboarding experience. The new system solves this problem.

The only downside that I see is that this requires special tools, awk and pandoc. Awk is readily available on all platforms we support, but pandoc must be installed in the runners. Fortunately, pandoc is available from both Homebrew and MacPorts. For Windows there is a package from the upstream website which works in msys2 just fine, if PATH is set up accordingly. On Arch and Debian/Ubuntu, pandoc is readily available in the official package repositories. So this shouldn't be a big issue.

Assignee
Assign to
Reviewers
Request review from
Time tracking
Source branch: gendoc