nim doc for a multi-module library too complicated

[jabbalaci]

Summary

If you have a multi-module library, then generating the docs for the modules + creating a theindex.html file that has all the exported things from every module is not that easy. nim doc should have an option to generate everything for a multi-module library.

Description

I figured out what commands are needed to achieve this goal. I put together a sample multi-module library, see here: https://github.com/jabbalaci/NimMultiModuleLibrary . In the README I explain the necessary steps.

[kaushalmodi]

Related: #9392

[haltcase]

Isn't this what nim doc --project is for? It's only recently been added though.

[krux02]

I feel sorry now. I was not aware of this feature yet. The commend line documentation of nim really needs to be improved, because I did not find it there.

[jabbalaci]

Isn't this what nim doc --project is for? It's only recently been added though.

I tried it in my sample project:

$ nim doc --project src/stuff.nim

It produces src/htmldocs/stuff.html, nothing else. No .idx files, no theindex.html.

[krux02]

In my opinion, nim doc should by default be recursive and generate as much documentation as possible. Generating the documentation of just one single file is really a very specific use case, it should not be in the base API.

[timotheecour]

It produces src/htmldocs/stuff.html, nothing else. No .idx files, no theindex.html.

see also --index:on flag (cf: #9392)

[jabbalaci]

see also --index:on flag (cf: #9392)

nim doc --project --index:on src/stuff.nim produces src/htmldocs/stuff.html and src/htmldocs/stuff.idx . The submodules in src/stuff/*.nim are left untouched. No theindex.html is generated.

Actually, what does --project do? Running nim doc --index:on src/stuff.nim I get the same things: an .html and an .idx file. The only difference is the location of the produced files. The .idx file is put in src/htmldocs, while the .html file is next to the source file.

[jabbalaci]

In addition, it'd be nice to generate links to the source code too. I couldn't make nim doc --docSeeSrcUrl work. If someone has an example, please share it.

[timotheecour]

i had added in #8423 git.commit and git.url flag, see use in travis.yaml; needs to be documented (see "for future PR" in that PR)
eg:

--git.commit:devel --git.url:https://github.com/nim-lang/Nim

see also: #6071 (comment)

now that #8423 was merged, we can close this after changing all references of --docSeeSrcUrl to --git.url and --git.commit

[Araq]

This is all now supported, check out the nimdoc/tester project setup.

[FedericoCeratto]

Related: #11074