Custom templates for documentation nodes
Nobody has claimed this yet.
- Dominant language
- Macaulay2
- Stars
- 435
- Forks
- 297
- Avg merge
- 4d 20h
- Merged PRs (30d)
- 11
Description
Every documentation node has the same underlying structure, but they serve different purposes; for instance, there are nodes that
- document methods
- document classes
- provide overviews
- serve as the landing page for a package
- are a tutorial
Because of these different uses, there should be different templates according to a node's purpose. Right now (from what I can tell), all nodes extract the SimpleDoc information and display in the order defined in getBody in help.m2: Headline, "Synopsis", Description, SourceCode, Acknowledgement, Contributors, References, Caveat, SeeAlso, Subnodes, "WaysToUse". In this setup, "WaysToUse" serves as the dumping ground for any additional documentation via documentationValue. So, as an example, the authors of a package will always be listed below the description (if one is provided) of the package.
A hacky workaround is to just use documentationValue directly to structure the page after detecting the type of node passed into getBody (see #4408 for an example of this). Presumably, a better system could exist for templating documentation nodes depending on their use-case (also mentioned as a TODO in help.m2).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in M2/Macaulay2/m2/help.m2, reading getBody, documentationValue, and the templating TODO, then review issue #4408 for the current workaround. Define how documentation node purposes map to templates and verify that each node type renders its intended sections without relying on WaysToUse as a catch-all.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100