AI-Generated Markdown Documentation#4307
Conversation
|
I'm a little confused about the purpose of this PR. Is it meant to be eventually merged, or just share what you've generated so far? |
Largely the latter and to elicit feedback from (generally anyone) in the community about the contents of the markdown files. No more additional files are being generated though (diminishing returns, most internal sub-directories have a Markdown file covering its contents). |
Relocates the generated Doxygen tree (html/ and xml/) plus the .nojekyll marker and pages.yml workflow that uploads M2/BUILD/build/Macaulay2/docs/ doxygen/html as the Pages artifact. Titles were rewritten from /home/ubuntu/M2-docs/... to /home/ubuntu/M2-web/... so that future regen runs from this repo produce empty diffs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This reverts commit 7c5b9fb.
Squashed import of the doxygen-comment work previously hosted in the M2-docs companion repo (~641 small commits there, e.g. "Add class doxygen for foo, bar, baz"). Strictly additive: 12,279 insertions vs 521 deletions, where the deletions are trailing whitespace and a handful of older one-line \ingroup directives folded into the new file-level comment blocks. No semantic code changes. Source: M2-docs (github.com/andrew-tawfeek/M2-docs) master @ e080fbdc15. These comments are what populates https://atawfeek.com/M2-engine/docs/ when doxygen.sh regenerates against this tree. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…dule pins Strips three non-documentation layers that had accumulated on stable so that this branch's only diff vs Macaulay2/M2 development is the markdown documentation added by the "Documentation additions" commits: - Reverts d2599fa: 313 .hpp/.cpp/.h/.c files restored to upstream versions (the Doxygen comment blocks now live on the doxygen branch). - Removes 213 CMake/ninja build artifacts under M2/BUILD/build/ that had been force-added past the directory's own .gitignore. - Resets the bdwgc, fflas_ffpack, flint, frobby, givaro submodule SHAs to match upstream/development. - Restores M2/Macaulay2/e/README.md to its pre-doxygen markdown form (clobbered as a side effect of the earlier cp -a in d2599fa). Net diff vs upstream/development: only Documentation-additions markdown (.md files) and their README modifications. The compiled Doxygen site continues to deploy from the web branch; its C++ source of truth is now the doxygen branch. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
andrew-tawfeek
changed the title
| @@ -0,0 +1,40 @@ | |||
| name: Deploy Doxygen HTML to Pages | |||
There was a problem hiding this comment.
Just to point out a lesson learned from a couple years back: adding doxygen documentation (and in particular updating it regularly) increases the size of the repository unreasonable (iirc at least like 50mb per update, since every single file seemed to be regenerated, so this quickly ballooned to a ~400mb repository which made cloning a pain)
|
Also, just out of curiosity, how come some of the commits say "@andrew-tawfeek committed" and some say "Ubuntu committed"? |
2 participants
Description
Closes: None
The purpose of this pull request is to track/share with everyone the various Markdown files I'll be building around the M2 repository (with AI assistance, largely a mix of Claude Code and Codex). This is a draft pull request to encourage conversation, changes, and comments on the Markdown files being generated and edited.
This was started during the 2026 Workshop in Atlanta, GA. If you are here this week, please come talk to me about this in person if you have thoughts and/or changes you want me to make! I have followed the new draft pull request template found here.
AI Use
Please declare your use of AI on this pull request
Extent of AI Usage:
Claude Code (Opus 4.7) and Codex (GPT 5.5)
AI Details:
Model(s) Used: Claude Opus 4.7 (
xhigheffort) and GPT 5.5 (xhighthinking)AI Involvement Level:
How was AI used?
Markdown generation through strictly read-access to a clone of the M2 repository.
License
Choose one of the following