`nim doc --project --out:foo/bar.html` doesn't work; creates `foo/bar.html/` dir instead of a file

[kaushalmodi]

--out:foo/bar.html does not work with nim doc --project .. (works well with nim doc .. i.e. without --project)

Example

Create a test file t.nim like below:

# t.nim
proc foo*() =
  ## Some proc

and run this command:

nim doc --project --out:test1/index.html t.nim

Look at the generated docs' tree stucture.

Current Output

test1/
└── index.html/
   ├── dochack.js
   ├── nimdoc.out.css
   ├── t.html
   ├── t.idx
   └── theindex.html

Expected Output

A Nim project would have many nested Nim modules. So in that case, nim doc --project --out:foo/bar.html is expected to modify only the name of only main HTML page.

Also it doesn't make sense for --out to create a directory; we already have --outdir to do that.

test1/
├── dochack.js
├── nimdoc.out.css
├── index.html                <-- index.html instead of t.html
├── index.idx                 <-- index.idx instead of t.idx (for consistency, as name of this file doesn't matter)
└── theindex.html

Reason

Having the main or landing page export as index.html allows a better looking URL like https://USER.github.io/PROJECT/ (instead of https://USER.github.io/PROJECT/PROJECT.html).

Possible Solution

• I have a hack which I am not very proud of: I rename the PROJECT.html to index.html and then run sed to search/replace the references to that file in the search index files and theindex.html: https://github.com/kaushalmodi/nim_config/blob/84fee8a17f7fca302a4235d8d950ea16e0ee6748/config.nims#L381-L389

Additional Information

• This bug does not show up when running nim doc --out:.. without --project. Example: nim doc --out:test2/index.html t.nim generates:

  test2/
  ├── index.html
  └── nimdoc.out.css

• I have "pretty URL" landing pages (i.e. https://foo.bar/ instead of https:/foo.bar/zoo.html for all my projects). Being about to specify --out:dirname/index.html would be very useful!
• At the moment I am using the renaming + sed to search/replace hack in all my projects. Notice how the URLs can end in / as a result of the landing page being index.html. Few examples:
  • https://kaushalmodi.github.io/std_vector/
  • https://kaushalmodi.github.io/version/
  • https://kaushalmodi.github.io/p4ztag_to_json/
• By supporting nim doc --project --out:foo/index.html .., we wouldn't need to create a landing page separately. One example I know that exists in wild (/cc @c-blake ):
  • https://c-blake.github.io/cligen/
  • Above then links to https://c-blake.github.io/cligen/cligen.html

$ nim -v
Nim Compiler Version 1.3.5 [Linux: amd64]
Compiled at 2020-05-29
Copyright (c) 2006-2020 by Andreas Rumpf

git hash: 63d1a0289e872212e836559f92a785df51f4faac
active boot switches: -d:release

/cc @timotheecour

[timotheecour]

how about:

• fix docgen so that nim doc --project -o:htmldocs/myfoo.html sub/foo.nim does following: behaves like nim doc --project --outdir:htmldocs sub/main.nim and then adds a redirect page from htmldocs/myfoo.html to htmldocs/foo.html if these are 2 distinct files (or to wherever foo.html ends with according to other options in particular --docroot)

this could be the simplest, so that files end in predictable locations and in particular browsing to foo.html would also work.

And for the case where myfoo.html is index.html, it'll allow browsing via kaushalmodi.github.io/std_vector/ as in your example which would redirect to kaushalmodi.github.io/std_vector/std_vector.html in your case

[kaushalmodi]

so that files end in predictable locations

We shouldn't need to predict the file locations. Some would expect an index.html while some would expect a PRJ.html. But that should not matter as the project repo will be putting in the correct hyperlink.

Adding redirection page, etc is entering the realm of designing a static site generator. Instead we should just make --out generate the specified file instead of a directory.

[kaushalmodi]

Another option is to make --out throw and error if used with --project and add a --prettyUrls option.

[timotheecour]

We shouldn't need to predict the file locations

• note that file locations are used in theindex.html and module cross references (ok, those can be fixed to take into account renaming, we have control over how these are generated)
• but they're also used in human written doc comment links, eg:

  # in main.nim
  proc baz*(a: int) = discard
  proc baz*(a: float) =
  ## see also `baz <main.html#baz,int>`_

  or in some readme.md:

see [main fail](main.html)

the redirect would keep all links working.

Adding redirection page, etc is entering the realm of designing a static site generator

nah it's really simple:

<html>
<head>
<meta http-equiv="refresh" content="0; URL='nim.html'" />
</head>
</html>

or:

<html>
<body>
<script type="text/javascript">
  window.location.href = "nim.html"; // or: window.location.replace("nim.html");
</script>
</body>
</html>

I just tried it, it works great, and all links keep working too.

[kaushalmodi]

but they're also used in human written doc comment links,

Yes, but the project author who uses --out:index.html should how to cross-reference them in their own project. May be your point is valid for projects receiving a high influx of PR's. But still, this seems to be a really minor "issue".

For my projects at least, I wouldn't want the extra noise of extra html page created for each .nim file. It just boils down to the project author's preference on how the doc HTML should be named, and I think that the --out should solve that for --project just as it does for nim doc without --project.

nah it's really simple:

:)

I vaguely remember that with redirections, 301 redirections are the only ones recommendated. Meta refreshes like you suggested are frowned upon and not usually good for indexing by search engines. Ref: https://moz.com/learn/seo/redirection

It's a completely different territory than simple doc generation.

For the purpose of this issue, let's brainstorm how --project + --out should behave.

[timotheecour]

Yes, but the project author who uses --out:index.html should how to cross-reference them in their own project.

that's not good, now when you write doc comment links you'd then have to know how the main module is going to be renamed; what if a module is used in different contexts? what if you're changing which one is the main module? all links get broken.

what if someone else is generating docs for that module? (eg: it should be feasible for nimble to generate docs for all packages, or nim to generate docs for all important_packages, or some org to generate docs for a number of projects under its umbrella etc)

I vaguely remember that with redirections, 301 redirections are the only ones recommendated. Meta refreshes like you suggested are frowned upon and not usually good for indexing by search engines. Ref: moz.com/learn/seo/redirection

adding <link rel="canonical" href="nim.html" /> does the trick see https://stackoverflow.com/a/19717455/1426932:

As for Google Bot, it treats <link rel="canonical" href= as 301 redirect, the effect is that you get your pages reindexed and that is what you want.

<html>
<head>
<meta http-equiv="refresh" content="0; URL='nim.html'" />
<link rel="canonical" href="nim.html" />
</head>
</html>

Redirect provides a simple and practical fix for that, with similar behavior as symlinks or aliases.

• in fact, IMO --project should just go ahead and create index.html (via redirect) by default, since as you mentioned it makes navigating easier

the more uniform and simple doc creation is, the easier it is to interoperate. That's why i automated index generation when using --project; by default it should all "just work" with sane defaults and the simplest command line. And that's also why i'm automating --git:branch etc tags so that it works out of the box without customization needed

[kaushalmodi]

now when you write doc comment links you'd then have to know how the main module is going to be renamed; what if a module is used in different contexts? what if you're changing which one is the main module? all links get broken.

First enough. That's a valid point.

Redirect provides a simple and practical fix for that, with similar behavior as symlinks or aliases.

Ok. Just to confirm that you are proposing to do this just for the main module's page? If not and if we want to do this for submodules too, it becomes a bit hairy.. we need to spec it out properly with all cases. E.g. what if we have submodules proj/sub1.nim, proj/sub2.nim? For those, there won't be a clear way to create redirect pages.

So to summarize:

• When user does nim doc --out:foo/index.html bar.nim,
  • That applies only to the main doc page i.e. for bar.nim if using with --project
  • The index.html will be a meta refresh page to foo/bar.html (though, need to check if anchorized links also get redirected i.e foo/#abc -> foo/bar.html#abc)
  • This works the same way with or without --project

[timotheecour]

proposing to do this just for the main module's page

yes, where main is whatever file is given to a nim doc command

The index.html will be a meta refresh page to foo/bar.html

yes (more precisely, to wherever bar.html is generated which depends on --docroot)

need to check if anchorized links also get redirected

they don't (but should be possible with js) but I don't think that's needed since index.html would just be a "landing" (redirection) page for convenience, and all docgen links would just be links after redirection so you'd normally never see a foo/#abc, you'd only see foo/bar.html#abc (nor would you want external references to foo/#abc)

This works the same way with or without --project

the case without --project is maybe a bit more controversial, but we can implement proposal just for --project for now.

• arguments to use redirect even without --project: same arguments as given above (avoiding broken links) and consistency.
• arguments against: if user wants to do smthg like:

  nim doc -b:js -o:htmldocs/foo_js.html foo.nim
  nim doc -b:cpp -o:htmldocs/foo_cpp.html foo.nim

(counter argument:

• they could use nim doc -b:js -o:htmldocs/js/foo.html foo.nim;
• that would make cross-module links broken unless some kind of module map is provided to compiler )

[kaushalmodi]

I don't think that's needed since index.html would just be a "landing" (redirection) page for convenience, and all docgen links would just be links after redirection so you'd normally never see a foo/#abc, you'd only see foo/bar.html#abc

Ok. Makes sense.

the case without --project is maybe a bit more controversial, but we can implement proposal just for --project for now.

Ok. Sounds good.