search

c-blake / cligen

Nim library to infer/generate command-line-interfaces / option / argument parsing; Docs at
https://c-blake.github.io/cligen/
ISC License
501 stars 23 forks source link

Add workflow to generate API docs #152 #153

Closed jiro4989 closed 4 years ago

jiro4989 commented 4 years ago

This change updates API docs when master branch was pushed. And I changed publishing sources, from docs directory to gh-pages branch .

So, need changing repository settings. See Choosing a publishing source - GitHub Pages.

Under "GitHub Pages", use the Source drop-down menu and select a publishing source.

You have to select gh-pages branch.

c-blake commented 4 years ago

Ok. Tagging @kaushalmodi since he just raised an issue over at Nim-core that may impact the best way to go here.

Documentation seems to only work so well. Bleeding edge-up-to-date generated docs are nice & all, but pointers on the Wiki to test programs/concrete use cases might help the confused more.

kaushalmodi commented 4 years ago

Certainly, we need the autogenerated docs for API documentation, and then the Wiki pages for "recipes".

As the docs get improved on Nim devel, the cligen API docs will improve automatically.

c-blake commented 4 years ago

Anyway, if there is no --exclude we might have to enumerate the files we want docs for one by one instead of using the --project flag. It certainly seems too stringent a bar to insist every .nim file needs to have fully valid doc comments at all times for that to work.

If @jiro4989 can't figure that out, I'm happy to wait for Kaushal to get to a computer and try some things. No rush. Someone who knows rST better than I do can probably suggest/fix that stropped || bit..maybe backslashes.

jiro4989 commented 4 years ago

I think that installing devel --latest compiler needs much time. https://github.com/c-blake/cligen/runs/723535951?check_suite_focus=true ( 7 minutes ).

CI-workflow is able to run generation when branch is only master. Need change?

c-blake commented 4 years ago

Well, 3 min or 7 min is not too bad. 2x variation I could believe might come from simultaneous load on the bare metal of whatever virtual host is running things. As I mentioned, the PR traffic is quite low, and this is really more for those other people than for me. Anyway, I don't know for sure, but think most Nim people use HEAD from a few days..to a few weeks ago. So, it probably helps more to test against the latest.

c-blake commented 4 years ago

Also, the README.md has links to the old .html files. We may need to update those if these new files are in a new location. That doesn't need to be immediate, though.

c-blake commented 4 years ago

Looks pretty good to me. We can merge when @kaushalmodi takes a look and confirms as well.

kaushalmodi commented 4 years ago

The PR looks great. I confirm by checking out this PR branch and running nim doc --project cligen.nim that the page looks great:

image

It just needs a brief introduction about what this package is.. for a casual user who lands up on the cligen homepage.. at the very minimum a brief introduction and a link on that page to the source GitHub repo (e.g. this introduction in RST in the source file -> https://kaushalmodi.github.io/version/ ) .. but that is of course outside the discussion of this PR.

@jiro4989 I really appreciate you working on this PR.

c-blake commented 4 years ago

Other PRs on this are welcome, @kaushalmodi . Mostly I try to make the README.md the one initial entry point everyone should read at least once. Most seem not to or to forget things if they do as various questions that come up are in there about 65% of the time. It's not really that long, either. Anyway, it's much more than just one paragraph, though.

jiro4989 commented 4 years ago

cligen.html is not found yet. Please set a gh-pages if this configuration is not set.

See Choosing a publishing source - GitHub Pages.

Under "GitHub Pages", use the Source drop-down menu and select a publishing source.

gh-pages branch

c-blake commented 4 years ago

Shouldn't we use the master branch? I thought gh-pages was just a feature branch for your PR.

c-blake commented 4 years ago

(I do see they use gh-pages even in their instructions...It's just confusing to allocate a branch as a publishing source if you ask me...)

c-blake commented 4 years ago

Well, that seems to have fixed the links off of the README. Thanks, @jiro4989 .

kaushalmodi commented 4 years ago

gh-pages is the conventional GitHub Pages recognized by GitHub for publishing docs. You just need to go to settings and pick that branch for publishing to USER.github.iio/PROJ.

If you ask my preference, I like that a lot more than HTML change noise appearing in the master branch.

c-blake commented 4 years ago

Maybe more than master branch HTML - I'm with you there, but I'm not sure why it's a branch at all instead of just "its own thing". Making it a branch never intended to be merged seems like an abuse of the concept. The repo is providing little more than a subnamespace to the account (for that doc thing). Anyway, it's neither here nor their as it's "just what they do". I was mostly explaining my question.