Macaulay2 / Macaulay2/M2

Custom templates for documentation nodes

Open
#4,409 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Documentation
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.