search

click-contrib / sphinx-click

A Sphinx plugin to automatically document click-based applications
MIT License
212 stars 57 forks source link

Custom configuration #67

Closed ssomnath closed 3 years ago

ssomnath commented 3 years ago

Hello, I am trying to document the CLI here. I have some general questions:

  1. I am interested in generating a separate documentation page per click command sort of like how sphinx already does for typical python code. Is it possible to do this? Would I just have to manually create separate .rst files per click group?
  2. Is it possible to script / automate (recursively) things such that there is no need to manually add each group in index.rst?
  3. Is it possible to generate a tree or table of click groups and commands just like typical sphinx documentation?

The developer of the CLI I am trying to document appears to have used some custom click configurations to enable autocompletion etc. Consequently, I am not able to follow the Hello World example provided in the documentation. I get the following error when trying to document their CLI.py this way in index.rst:

.. click:: datafed:_cli
  :prog: datafed
  :nested: full

This is the error I get:

/DataFed/python/datafed_pkg/docs/source/index.rst:28: WARNING: Module "datafed" has no attribute "_cli".

How should I be configuring index.rst correctly?

Many thanks in advance!

stephenfin commented 3 years ago

Six months late, but better that than never 😅

Hello, I am trying to document the CLI here. I have some general questions:

1. I am interested in generating a separate documentation page per click command sort of like how sphinx already does for typical python code. Is it possible to do this? Would I just have to manually create separate `.rst` files per click group?

Yes. It would be possible to auto-generate docs but I haven't had a need for this and likely won't have time to add this functionality for a while. If someone were to implement this, they could probably hook into Sphinx's event system and generate documents that use the directive. PRs welcome.

2. Is it possible to script / automate (recursively) things such that there is no need to manually add each group in `index.rst`?

You mean if you did the above?

.. toctree::
    :glob:

    *

Should do the trick.

3. Is it possible to generate a tree or table of click groups and commands just [like typical sphinx documentation](https://pycroscopy.github.io/sidpy/_autosummary/sidpy.html#)?

This is basically 1. Doesn't exist but would be easy to add if someone had the inclination.

The developer of the CLI I am trying to document appears to have used some custom click configurations to enable autocompletion etc. Consequently, I am not able to follow the Hello World example provided in the documentation. I get the following error when trying to document their CLI.py this way in index.rst:

.. click:: datafed:_cli
  :prog: datafed
  :nested: full

This is the error I get:

/DataFed/python/datafed_pkg/docs/source/index.rst:28: WARNING: Module "datafed" has no attribute "_cli".

How should I be configuring index.rst correctly?

Sounds like _cli doesn't exist. You should be able to open python3 (in a virtualenv if needed) and do from datafed import _cli. If this fails, your path is wrong. Look at the source and figure out where you should be importing from. Once you import, you can use type(_cli) to make sure it's the thing you expected.

Many thanks in advance!

Hth.