search

Macaulay2 / M2

The primary source code repository for Macaulay2, a system for computing in commutative algebra, algebraic geometry and related fields.
https://macaulay2.com
347 stars 231 forks source link

classification of functions in a package #1000

Closed DanGrayson closed 4 years ago

DanGrayson commented 5 years ago

Frank Schreyer and David Eisenbud suggest that a package's documentation should be able to put the documentation nodes for functions into various subheadings, as manually illustrated here: https://faculty.math.illinois.edu/Macaulay2/doc/Macaulay2-1.14/share/doc/Macaulay2/K3Carpets/html/.

mahrud commented 4 years ago

Writing the front page documentation of a package is essentially like designing a website. We could probably provide examples to make this easier, or maybe add an optional SimpleDoc tag for grouping?

DanGrayson commented 4 years ago

This would be a good application of "Subnodes", an option to "document" and is available in SimpleDoc, as it is how a sequential book is organized, too.

mahrud commented 4 years ago

Added in the SimpleDoc PR. Subnode can be used within Description. The syntax is more advanced, in particular, it supports nesting and @...@ replacement.

mahrud commented 4 years ago

As an example, this:

    Subnodes
      :Special characters
        :Wildcard
          @TT "."@  -- match any character except the newline character
        :Anchors
          @TT "^"@  -- match the beginning of the string or the beginning of a line
          @TT "$"@  -- match the end of the string or the end of a line

Turns into this:

image

If the line doesn't start with ":" or "@", then it is treated as a documentation key and passed through TOH as usual.