[DOC] auto doc main CLI #463
Conversation
|
Thank you for opening this !
Best,
Jakub
… On Aug 4, 2022, at 5:21 AM, Remi Gau ***@***.***> wrote:
related to #461
in case someone feels like working on this. I am opening a draft here.
from my quick look it seems that all the many options are not automatically capture, so documentation automation may require refactoring some of the cli code. Or there is a way to make auto click figure this out but I am not sure.
You can view, comment on, or merge this pull request online at:
#463
Commit Summary
18abc87 basic set up for auto doc main CLI
File Changes (4 files)
M docs/conf.py (1)
A docs/user_guide/cli_auto.rst (7)
M docs/user_guide/index.rst (1)
M setup.cfg (1)
Patch Links:
https://github.com/ReproNim/neurodocker/pull/463.patch
https://github.com/ReproNim/neurodocker/pull/463.diff
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
|
|
@Remi-Gau - what is the status of this? |
From. Memory there was some issue with click I think. Need to double check. |
Codecov ReportPatch has no changes to coverable lines. 📢 Thoughts on this report? Let us know!. |
|
retried... it works... meaning it does not crash... but the generated doc is underwhelming...
Apparently this sphinx-click extension cannot capture all the options... At least in the way this is set up. |
|
Tried a different strategy: simply generate the help section with a bash script, dump it into a text file and include it in the rst. It looks more "packed" than the previous version but at least it will always be up to date.
|
| html_theme_options = { | ||
| "use_edit_page_button": True, | ||
| "icon_links": [ | ||
| { | ||
| "name": "GitHub", | ||
| "url": "https://github.com/ReproNim/neurodocker", | ||
| "icon": "fa-brands fa-github", | ||
| }, | ||
| { | ||
| "name": "Docker Hub", | ||
| "url": "https://hub.docker.com/r/repronim/neurodocker", | ||
| "icon": "fa-brands fa-docker", | ||
| }, | ||
| ], | ||
| } | ||
|
|
||
|
|
||
| html_context = { | ||
| "github_user": "ReproNim", | ||
| "github_repo": "neurodocker", | ||
| "github_version": "master", | ||
| "doc_path": "docs", | ||
| } | ||
|
|
There was a problem hiding this comment.
Those are just to add links to the repos on github or docker hub in the navbar and to add an "edit source" link when browsing the doc.
There was a problem hiding this comment.
thanks for adding this. i always appreciate when i'm able to easily browse the source from the documentation.
There was a problem hiding this comment.
looks great @Remi-Gau thanks very much! i only see one change that needs to be made. can you remove the docker badge that pointed to the kaczmarj dockerhub namespace? let's only have one docker badge, that points to repronim's account.
| html_theme_options = { | ||
| "use_edit_page_button": True, | ||
| "icon_links": [ | ||
| { | ||
| "name": "GitHub", | ||
| "url": "https://github.com/ReproNim/neurodocker", | ||
| "icon": "fa-brands fa-github", | ||
| }, | ||
| { | ||
| "name": "Docker Hub", | ||
| "url": "https://hub.docker.com/r/repronim/neurodocker", | ||
| "icon": "fa-brands fa-docker", | ||
| }, | ||
| ], | ||
| } | ||
|
|
||
|
|
||
| html_context = { | ||
| "github_user": "ReproNim", | ||
| "github_repo": "neurodocker", | ||
| "github_version": "master", | ||
| "doc_path": "docs", | ||
| } | ||
|
|
There was a problem hiding this comment.
thanks for adding this. i always appreciate when i'm able to easily browse the source from the documentation.
Co-authored-by: Jakub Kaczmarzyk <[email protected]>
|
will wait for CI to finish and merge |
in case someone feels like working on this. I am opening a draft here.
from my quick look it seems that all the many options are not automatically capture, so documentation automation may require refactoring some of the cli code. Or there is a way to make auto click figure this out but I am not sure.