Travis config for build checks using Nim devel and auto doc generation

[kaushalmodi]

Hello,

I'd like to suggest using Travis (or any CI of your choice) to check cligen builds using Nim devel (I do that using the weekly Travis cron for my little packages).

In addition, it's really easy to update the docs on each commit.

Here's an example travis config from one of my projects:

• https://github.com/kaushalmodi/p4ztag_to_json/blob/master/.travis.yml

I have designed it so that I can be lazy and copy/paste it to each new Nim project of mine (nothing related to the project is hard-coded in there).

With that config, having set $GITHUB_OAUTH_TOKEN in Travis config portal, I get https://kaushalmodi.github.io/p4ztag_to_json/.

[c-blake]

I have had really bad experiences with these cloud hosted build services taking way too long to run, and only after commits. I run my ./test.sh in literally about 2 seconds flat wall clock time before commits. This way I (mostly) avoid committing stuff that breaks. The after the fact test on Windows might be nice someday, but there is such weak OS dependence on anything cligen does..

The auto-doc gen stuff might be nice, though. I've been just hosting it in the github repo itself instead of github.io.

[c-blake]

Also, I build nim-devel and run my test.sh script like 2..10 times per week and it's never been more than a small fraction of a day that an issue went undetected. So, to me, only the doc stuff adds any real value, but I also can just run my doc.sh whenever..It just feels lame to keep all that generated HTML under version control just to make github host the content.

[kaushalmodi]

Also, I build nim-devel and run my test.sh script like 2..10 times per week and it's never been more than a small fraction of a day that an issue went undetected.

Even if you don't run tests on travis, just a compile check using Nim devel on each commit would be useful IMO. But it's understood if you don't want to do that.

It just feels lame to keep all that generated HTML under version control just to make github host the content.

Yeah, I agree. Moving doc generation to travis will also give you a nice link: https://c-blake.github.io/cligen/ .

[c-blake]

If you mean on each of my own commits, like I said - I check pre-commit or at least pre-git push. If you mean on each of Nim core's commits to nim-devel..That seems too high traffic to me..Sometimes many times per day. Also, cligen is pretty popular. Other people catch problems fast. The one time I was "later" than the general crew it was only by 2 hours (about half way into a multi-hour bicycle ride I was on). And they fixed Nim rather than cligen. So, I'm really not too worried about that. I'll look into the doc gen this weekend, though.

[kaushalmodi]

If you mean on each of my own commits

Yes, after each commit to cligen, latest Nim devel is built if a newer commit there has happened since the last cligen build on Travis.

I'll look into the doc gen this weekend, though.

Thanks.

[c-blake]

Well, I moved the generated HTML into docs/ and created https://c-blake.github.io/cligen/. So, you've got your shorter URIs if that was what you were after. I even added an index.html if you wanted to bookmark just the top-level or something.

I don't really see how to push HTML changes without either dealing with some CI/Travis hair or committing the HTML to the git repo. So, I'll probably just run doc.sh when I update something in the doc comments which is honestly not that often.

As I mentioned, for me using the CI vs my test.sh script would slow me down from "2 seconds pre-commit" to maybe checking in garbage/waiting for some CI to finish neither of which is at all a welcome change to my workflow. When I'm updating my documentation, I also sometimes preview the HTML locally before committing to see what it looks like/if I made some RST error. A fast/no VC interaction edit-check-edit-again cycle is too helpful to give up for no real gains, IMO.

The only real value I see in CI for this project is fast(er) detection of Nim devel breaking my code post every Nim core commit. Such detection is already really quite fast, though.

Don't get me wrong - I see the value in regression tests/auto-doc generation. I just think it should be all "pre-commit". Hanging that activity off the back side of a VC system strikes me as actively promoting bad habits of commit-first-ask-questions-later over better habits of pre-commit checks.

A much bigger testing enhancement would be to add a bunch of (pre-commit) behavioral tests beyond the help message dumping test.sh currently does. Work along these lines was started in https://github.com/timotheecour/vitanim/blob/master/testcases/tests/t0000.nim and https://github.com/timotheecour/vitanim/blob/master/testcases/tests/t0002.nim .

[kaushalmodi]

I'd just like to add that it would be nice to advertise the cligen docs link in this repo meta header:

You'd need to click the "Edit" button you see when you visit this repo's homepage and add the docs URL in that special "Website" field.

[c-blake]

Done. The index.html is pretty spartan, though.

[kaushalmodi]

The index.html is pretty spartan, though.

I think that's alright. At least the new users can quickly see that effort has been put in to create the doc pages linked in that index.html.

[kaushalmodi]

About the index.html creation, the nim doc has a --project switch which can probably be used to auto create it. I haven't used it, but I've seen it in the nim doc tests.

---

Edit: OK, it probably doesn't create the index page, but it does recursively create all the pages related to the project, and maybe sensibly interlink them too: https://nim-lang.org/docs/docgen.html#related-options-project-switch

[c-blake]

Thanks. I'll look into that tomorrow.