issue warning for documentation nodes without an example
Nobody has claimed this yet.
- 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
- 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 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