todogroup/repolinter

Enhance Documentation in README

Brend-Smits opened this issue · 1 comments

Brend-Smits commented

Issue Report

Documentation is published to GH Pages, but it is poorly advertised within the repository. It is hard to find where to read up on different parts of Repolinter.

Expected Behavior

  • Clarify and clean up the README to include less information, and more linking to relevant documentation pages.
  • We should update the repository settings to reference the GH Pages deployment.
  • Ensure that GH Pages documentation is still relevant and automatically published/updated
hyandell commented

Perhaps backwards. I have updated the repo settings to refer to the page.

GitHub Pages wise, it is set to build from the gh-pages branch's root directory. It's a bit clunky, but does relate to the last release (so it's relevant in the way npm is relevant).

Looking at the branch, I was surprised to see it isn't a merge of the docs directory. It's html files generated by this workflow: https://github.com/todogroup/repolinter/blob/main/.github/workflows/docs.yaml - presumably so it can incorporate the apidocs. Presumably documentation.yml also an input. This makes me think it is not the last release but latest content. For example; #227 is deployed, which is after the last release.

The index feels clunky - too much content in there as you said. Seems to be concatenating the readme with other pages.