Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

No link to std/exitprocs in docs (+enumerate,jsonutils etc) #16046

Closed
Benjamin-Lee opened this issue Nov 19, 2020 · 5 comments
Closed

No link to std/exitprocs in docs (+enumerate,jsonutils etc) #16046

Benjamin-Lee opened this issue Nov 19, 2020 · 5 comments
Labels
Documentation Generation Related to documentation generation (but not content). Low Priority

Comments

@Benjamin-Lee
Copy link
Contributor

See #15694 for discussion. I tried importing exitprocs only to get an error saying it couldn't open it. Turns out it's in std and the docs page makes no mention of how to import it. In addition, it's not listed in the stdlib directory.

@timotheecour
Copy link
Member

timotheecour commented Nov 19, 2020

In addition, it's not listed in the stdlib directory

see #15694 (comment)

note that search works:

image

if you click on the link there's at least now a Source link that shows it's under Nim/lib/std/exitprocs.nim

Turns out it's in std

like all new modules in stdlib.
it'd be redundant to mention this "by hand" in each stdlib module.

instead, this is how we can improve things:

automatically show proper fully qualified import syntax in docs

in docs, instead of showing the module name (exitprocs for https://nim-lang.github.io/Nim/exitprocs.html) or depending on --project (+docroot) option, the relative path (src/fusion/pools for https://nim-lang.github.io/fusion/src/fusion/pools.html), we should also show the import syntax eg:

for exitprocs: import std/exitprocs
for tables: import std/tables # even if relative path is under lib/pure/collections/tables.nim)
for pools: import fusion/pools

this should be auto-generated (not mentioned for each module in some doc comment), otherwise it's a total waste of time.

make sure each stdlib module is referenced in doc/lib.rst (https://nim-lang.github.io/Nim/lib.html)

kochdocs could add some logic to check that all docgen'd stdlib modules are mentioned in lib.rst, that way, it'd always stay in sync.

I'm sure other modules are missing.

@timotheecour timotheecour added Documentation Generation Related to documentation generation (but not content). Low Priority labels Nov 19, 2020
@Benjamin-Lee
Copy link
Contributor Author

Autogenerating the import syntax in the docs would be great

@Benjamin-Lee
Copy link
Contributor Author

Also https://nim-lang.org/docs/jsonutils.html is unlinked.

@timotheecour timotheecour changed the title No link to std/exitprocs in docs No link to std/exitprocs in docs (+enumerate,jsonutils etc) Nov 19, 2020
@timotheecour
Copy link
Member

#15694 (comment)
If not, I'm happy to PR it.

Note that https://nim-lang.github.io/Nim/theindex.html already references all modules (including exitprocs etc), and in general automated solutions are preferable.
A PR to automatically add proper import syntax would be welcome, IMO, but check with others first.

@ringabout
Copy link
Member

Duplicate of #16656

@ringabout ringabout marked this as a duplicate of #16656 Sep 24, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation Generation Related to documentation generation (but not content). Low Priority
Projects
None yet
Development

No branches or pull requests

3 participants