Collection of ideas for nim doc improvements (low priority)

[haxscramper]

For now, I just want to have a single place to put all the ideas about improvements on the nim doc command - it is not a major priority right now (it is not on the main roadmap since it can be easily categorized as "bells and whistles improvements" - until we have a fundamental parts of the language fixed all distractions can be somewhat postponed).

Having said that, nim doc output is in absolutely abysmal state, and I feel that at least having a general improvement direction is a good step.

• It is not possible to properly produce project-wide documentation - nim doc --project output
  1. Does not have a main welcome.rst page unless specifically configured and creates an absolutely insane page with all modules linked into it
  2. No way to navigate from currently opened module page to adjacent entries, only back to the index
  3. Sometimes completely refuses to work properly, only generating documentation for a small subset of available API, or includes completely unrelated packages to main index (see hmisc index).
• Output is not grouped by "categories" which does not make any sense - I have a ton of procs, then a pile of macros, followed by another group of iterators. Grouping can be made by first argument, by user-defined tags and so on. This has already been solved multiple times, we can just reuse rust/doxygen etc. formatting.
• No machine-readable output - --json produces a barely formatted original source code
• Does not even try to understand the code - using declarations are not expanded, when sections are either hidden or missing field types, none of the documentation comments are properly parsed out in fields/enums.
• Does not support any way to semantically annotate elements - RST supports "interpreted text" annotations, like :idx:`entry` - that one can be reused. Implicitly triggering semantics each time argumentName is encountered in the body is probably an overkill, but

  - :arg:`name` - optionally disable processing of the hidden files

  Seems like an acceptable solution.

[haxscramper]

Language specification is built using block: sections and documentation comments - ideally, I want nim doc to process the spec and tests as a part of the documentation. Making it into a one-off script (like current koch documentation handling) is possible, but I see no reason why it can't be implemented as a generalized solution.

block subtype_match:
  ## Subtype match - argument is a subtype of the procedure argument. Note that this
  ## requirement is related to inheritance (because of subtyping), but does not
  ## replace `method`'s functionality. It also works with `{.inheritable.}` types and
  ## `object of RootObj` (in addition to `ref object of RootObj`) whereas `method`
  ## requires `ref` to be used.
  block inheritable_pragma:
    ## `{.inheritable.}` provides subtyping capabilities
    type
      Base {.inheritable.} = object
        field: int

      Derived = object of Base
        field2: int

The whole spec could easily be turned into a manual.rst (preferably a multipage document with a proper sidebar, we can generate both single and multi-version of the spec, it is not that hard).

[haxscramper]

Making nim doc CI ready (at least for GitHub, which is the only thing it really supports anyway) is also trivial and would alleviate the pain of having to do things like these each time for each project. GITHUB_REPOSITORY, GITHUB_SHA, GITHUB_REF etc. are all available as environment variables.

          nimble doc --project --outdir:docs \
            '--git.url:https://github.com/${{ github.repository }}' \
            '--git.commit:${{ github.sha }}' \
            "--git.devel:$branch" \
            gittyup.nim

[haxscramper]

Forgot to mention Sourcetrail support is going to be a good feature to have as well - it is easy to implement and maintain (there is a question of reusing c++ db driver vs rewriting it in nim - latter one is quite easy to do, and the code won't change afterwards). Sourcetrail support is already implemented for haxdoc, just need to be cleaned up and simplified for nim doc.

[haxscramper]

Alternatively, sourcetrail can be implemented as a tool that uses output from the nim doc json format to build the necessary object database. Decouple different functionality into different tools and stabilize interchange format these tools use.

[haxscramper]

All features of koch docs (like the ability to actually generate project with more than one .rst file for documentation) should be available for regular users.

[iacore]

Priority: Remove Nim Logo at the bottom of the doc page. It's probably trademark infringement