search

gap-packages / AutoDoc

A GAP Package to produce documentation.
https://gap-packages.github.io/AutoDoc/
Other
8 stars 11 forks source link

Integrate publishing of docs to GitHub Wikis #269

Open ZachNewbery opened 1 year ago

ZachNewbery commented 1 year ago

While having HTML package manuals is a good way for users to easily access documentation on demand, GitHub's wikis feature might provide a more centralised method for users to not even have to leave the repository to learn about the package.

Currently, Wikis seems to support locally editing markdown files to be published to the repository, and can be cloned. Of course, this may lose out of some of the HTML features that make GAP documentation unique, so may be suited for a selected subset of AutoDoc comments (e.g. development/usage guides).

fingolfin commented 1 year ago

Multiple thoughts...

  1. I am not quite sure what this issue is proposing, it seems somewhat vague? "Use GitHub wiki somehow" OK, but how? What is the workflow you have in mind? Who would do what?
  2. AutoDoc is just a front end for GAPDoc, not fully standalone, so I am not even sure this is the right place to discuss this (but then I am also not completely sure what we are discussing, so ... ;-) ).
  3. what exactly is the problem you want to solve here / what are concrete advantages you have in mind of the Wiki over a separate web page like https://gap-packages.github.io/AutoDoc/doc/chap0.html
  4. Wikis to me are primarily for user generated and modified content, not for the output of a tool
    • in particular, nothing would stop a user from editing those Wikis, but those edits would be lost next time the Wiki is updated from the sources
    • perhaps you had in mind to completely replace the manuals (i.e. delete the sources and migrate to GitHub wikis 100%) but that would loose a ton of features. Like, different manuals for different versions (e.g. there is no way to "tag" Wikis in GitHub and view the Wiki as it was at a specific tag, is there?)
  5. long term, beware of vendor lockin: GitHub is great for now, but there may come the day where one will want to migrate away from it; anything that is built atop it then will need to be replaced
ZachNewbery commented 1 year ago

It was more as a possible direction - haven't really thought it through just yet but felt it might be something worth discussing as it seemed promising.

I was imagining that alongside the documentation generated by AutoDoc there may be some special files/guides written by package authors that are picked up and published to the repository wiki. This could possibly include things such as working with certain errors, or how a developer can extend the package in a way that conforms to what already exists.

The more concrete advantages would likely be centralising the location of developmental tools for a package, as well as serving as more of a guidelines area over raw function documentation (i.e. as a way for newer developers to understand how to work with the package rather than needed to understand and work through the function docs?). Might be a lot less overwhelming for new users as well, and could contain tutorials.

As far as I'm aware, the files themselves that the wiki consist of are mostly markdown so can be migrated should there be vendor locking. I'm not 100% sure but ideally the tool would be able to update 'articles' within the wiki, and users could comment on them to propose edits/ask questions about the content without cluttering up the Issues tracker etc

ZachNewbery commented 1 year ago

I do agree it might be better suited as a standalone package though possibly, or integrated within GAPDoc itself