Wishlist

[haxscramper]

This issue could be used as an initial wishlist for different suggestions/ideas. I'm pasting verbatim list from @mratsim 's arraymancer comment

• [ ] Collect and export all public procs and types (exported from arraymancer.nim) into an API reference file.
  • [ ] sqlite database
  • [x] simple machine-readable XML and JSON format
• [ ] Possibility to add markdown files that would be categorized into Tutorials, How-Tos and Explanations
• [ ] Image in markdown support.
• [ ] Documentation wide search, for example using Algolia.
• [ ] Navigation menu (and no fiddling with viewports to try to fix the display).
• [x] No crash on c2nim generated wrapper for something as basic as *
• [ ] Single command to generate the documentation, can be integrated in CI.

Extras

• [x] Organize the API reference per module (either via folder organization or by introducing a tag).
• [ ] This is necessary to turn Arraymancer in some kind of monorepo.
• [x] Pass defined flags to handle when defined(cuda) or when defined(opencl)
• [ ] dark mode / theming
• [ ] support versioning (devel and latest release).

Ndoc

• [ ] Account for ideas in ndoc readme

C++ interop

• [ ] Support importing documentation (manpages/doxygen) from C/C++ libraries into nim code.

Export modes

• [ ] Manpage export #5
• [ ] Info export #6

[haxscramper]

After "some" work on the project, I can say most of this wishlist can be trivially implemented with current API, but there is one caveat - current implementation still provides only library API, that must be wrapped into higher-level helpers. Right now process is separated into three stages - extraction, processing (procedure reordering, grouping etc) and generation. Extraction stage is 99% finished right now - most of the information available to nim compiler is pulled out, sorted and placed in the database - define() checks, inheritance graphs, procedure usages (and tens of different usage scenarios https://github.com/haxscramper/haxdoc/blob/master/src/haxdoc/docentry.nim#L164), global variables and so on. Processing stage is in proof-of-concept stage right now.

Generation stage is mostly implemented for XML serialization. All it takes to create documentation for a file: https://github.com/haxscramper/haxdoc/blob/62798c56714b5ebe238de6df6c490904f4557b41/tests/tFromSimpleCode.nim#L143-L147 For package: https://github.com/haxscramper/haxdoc/blob/62798c56714b5ebe238de6df6c490904f4557b41/tests/tFromPackage.nim#L30. SQLite is also partially implemented, though right now I'm focusing on making it useful for understanding state of the code, rather than generation documentation from it. Things like checking number of usages for a particular function across all packages at once (by generating documentation for "important packages" for example, and then running one-liner query). SQLite database generation from XML serialized version: https://github.com/haxscramper/haxdoc/blob/62798c56714b5ebe238de6df6c490904f4557b41/tests/tFromSimpleCode.nim#L223-L225