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
  • 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).
• No crash on c2nim generated wrapper for something as basic as *
• Single command to generate the documentation, can be integrated in CI.

Extras

• 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.
• 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 [Request] Add manpage export #5
• Info export [Request] Add 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:

haxdoc/tests/tFromSimpleCode.nim

Lines 143 to 147 in 62798c5

	file.writeFile code
	block: # Generate initial DB
	let db = generateDocDb(file, fileLIb = some("main"))
	db.writeDbXml(dir, "compile-db")

For package:

haxdoc/tests/tFromPackage.nim

Line 30 in 62798c5

let db = docDbFromPackage(findPackage("hmisc", newVRAny()).get())

. 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:

haxdoc/tests/tFromSimpleCode.nim

Lines 223 to 225 in 62798c5

	if not exists(dir /. "compile-db" &. "hxde"): quit 0
	let db = loadDbXml(dir, "compile-db")
	db.writeDbSqlite(dir /. "compile.sqlite")