Mirror of forum.nim-lang.org

9017 :: Cant't change the name of main html file in the output of `nim doc`?

• monsoonman (orginal) [2022-03-16T08:32:04+01:00] view original

  I am generating docs of my module foo using the following command:

  
  nim doc --out:html --project src/foo.nim
  Run

  It generates html docs in the directory out with out/foo.html as the main html file. When I deploy foo on github pages, nothing shows up there because github pages accept index.html to be the starting point and it can't be found.

  Is there a way to change out/foo.html to out/index.html using a command line switch?

  Currently, I am manually moving out/foo.html to out/index.html.

---

• PMunch (orginal) [2022-03-16T08:45:51+01:00] view original

  I believe this is because if you had two modules in your project it's nice that they're named after the module they come from and not one simply being called index.html. Manually moving it (or just moving it from the same script that runs nim), or even just having a symlink from index.html to foo.html is probably the best solution.

---

• monsoonman (orginal) [2022-03-16T09:01:04+01:00] view original

  Thanks @PMuch. You are right.

  I have the following structure.

  
  src/
  ├── bmo.nim
  ├── bmopkg/
  │   ├── cli.nim
  │   ├── command.nim
  │   ├── common.nim
  │   ├── install.nim
  │   └── subcom.nim
  └── data/
      └── install_choco.ps1
  Run

  If I move data out of the src, it generates index.hml as main file.

---

• monsoonman (orginal) [2022-03-16T09:41:21+01:00] view original

  I misspoke. Even after moving the data folder out of the source tree, the main html file remains to be bmo.html and not index.html. I got confused because bmo.html was changed to index.html by nimble task. I'have updated the previous post.

---

• PMunch (orginal) [2022-03-16T10:35:59+01:00] view original

  No, I was saying that it would be a poor design by the compiler to output a index.html file. Of course if the user specifies that they want to rename a specific module to index.html then that could work, but then why not just throw mv mymodule.html index.html into your script, surely that's about the same length as the extra flags to nim doc would be..

---

• monsoonman (orginal) [2022-03-16T11:30:06+01:00] view original

  Ah, I see. Thanks for the explanation.

  Well, IMHO, it is really not about number of keystrokes but default behaviour. One usually expects index.html to be present in a website by default, and most web-browsers expects index.html to be the starting point (not sure if this is standard). So, it is not all unreasonable to expect nim doc that generates html by default is to generate an index.html file by default. My two cents.

---

• PMunch (orginal) [2022-03-16T12:25:30+01:00] view original

  It totally depends on the site though. Maybe you want index.html to be a "Welcome to this project, check out this video, or maybe the <documentation?>" with that last bit being a link to the actual documentation. In this case it would be super annoying if Nim generated an index.html file for you. Naming the HTML the same as the modules means that you can have things like docs/mymodule.html which is a nice descriptive URL. For your GitHub sites example maybe run pandoc on the README to generate an index.html file that then links to the documentation? Would serve as a nice welcome page and then take you on to the actual technical documentation for those who wants to read it.

---

• kaushalmodi (orginal) [2022-03-16T14:45:58+01:00] view original

  In static site generator lingo, it's a better convention to generate index.html so that we have "pretty URLs".

  • Ugly URL: example.com/foo.html. The ".html" is needed to be added in the URL.
  • Pretty URL: example.com/foo/index.html. Now that URL can be accessed using example.com/foo/ or example.com/foo. Of course this works only if the HTML pages are on a server. If you try to access offline using file:// protocol, you will need the full path foo/index.html.

  So there are pros and cons of both ugly and pretty URLs. Good thing is that it's pretty easy to convert the Ugly URLs to Pretty URLs using a Nimscript task like this.

---

• monsoonman (orginal) [2022-03-17T13:40:19+01:00] view original

  Converting README.md to index.html is a good idea.

---

• monsoonman (orginal) [2022-03-17T13:41:58+01:00] view original

  But having an option to change the main html file in nim doc is a reasonable feature request. No?

---