Macaulay2 / Macaulay2/M2

issue warning for documentation nodes without an example

Open
#3,842 1 comment 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

I'm looking at the package [SectionRing](https://macaulay2.com/doc/Macaulay2/share/doc/Macaulay2/SectionRing/html/index.html) for research and noticed a few things:
1. it would be good to issue a warning with the number of documentation nodes (at least those documenting a method) without an example, in order to encourage authors to add documentation (at the very least turn some tests into documentation examples with assertions).
2. in this package, `Divisor` and `Varieties` are imported but not exported, which has the unintended side effect that the documentation doesn't list `globallyGenerated(WeilDivisor)` and `mRegular(CoherentSheaf)` as missing documentation, but lists `globallyGenerated(Ideal)` and `mRegular(Ideal)`. I think this should at least be a warning.
3. this brings me to the third strange thing, which is that the documentation installs without a single message:
```m2
2025-05-22T17:51:04.9781430Z [567/710] Installing package SectionRing
2025-05-22T17:52:06.0148170Z [568/710] Installing package ExampleSystems
```
There's something wrong (with the documentation system) but I'm not sure what.

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 by reproducing the SectionRing documentation installation and inspect the documentation system's handling of missing examples and imported but unexported symbols. Compare the reported methods with the generated documentation and installation output; done means the relevant cases produce useful warnings without suppressing valid documentation.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.