Seamly2D
Seamly2D copied to clipboard
FashionFreedom
DOCS: Update code documentation
Update code documentation.
Options to consider:
| Tools | Task | URLs |
|---|---|---|
| Doxygen | Generate docs from code | Doxygen, Tutorial 1, Config GH Actions to run Doxygen, Tutorial 2, Create Doxygen script, Tutorial 3 |
| VSCode Doxygen comment generator | Insert Doxygen-friendly comments into code | Doxygen comment generator Tutorial |
| Sphinx + Breathe + Doxygen | Generate docs from code with better formatting | Sphinx Tutorial |
| Read the Docs | Hosts generated docs (free) in multiple formats | ReadTheDocs.org |
| Just the Docs | Create a Jekyll-themed static Github page with links to ReadTheDocs code docs, user manual, and other resources | Just the Docs GH page |
Is there a reason to use Sphinx and not just stick with Doxygen?
Sphinx doesn't output from C++ directly, and to use it you have to use Breathe as a bridge to Doxygen output along with building with CMake. . Too much work. It's not like we're needing to provide a really cool "visually un-noisey" looking API documentation to 1000's of users. If you want a really cool looking docs CSS them. Besides... I'm probably the only one who's ever bothered to even run Doxygen on the project. ;)
That being said... Since there currently are no API docs, "update" is not the word... it should be "Add". To that extent I can Add the Doxygen docs at anytime... in fact I just ran them again last night to aid in unraveling the code for implementing built in seam allowances. And no... IMO producing the docs automatically should NOT be in the CI.. It already takes too long as it is to build the apps.
@dscaskey I used to run Doxygen a while back and the results were difficult to understand. The Sphinx presentation at All Things Open looked great, so I added this issue.
please consider creating a script under /scripts that outputs Doxygen to a /docs folder.
When this issue was written we had a /docs folder with Doxygen docs published on our github webpage. But we received a few hostile comments that the docs weren't helpful. It's great that you find them helpful, so let's publish them again.
I'll begin with basic Doxygen docs & then we can decide where to go with this.