DOC: improve documentation (#106)

* add CLI modules documentation
* rename group in click CLIs to reduce confusion
* switch to RST for CLI modules docs, since MD support
appears to be incomplete/buggy in click-sphinx
* update documentation in few places

docs/api/idc_index.rst

@@ -1,5 +1,5 @@
-idc\_index package
-==================
+idc\_index package API
+=======================
 
 .. automodule:: idc_index
    :members:
@@ -16,3 +16,11 @@ idc\_index.index module
    :members:
    :undoc-members:
    :show-inheritance:
+
+idc\_index.cli module
+-----------------------
+
+.. automodule:: idc_index.cli
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/cli_tools.rst

@@ -0,0 +1,13 @@
+Command Line Interface tools
+============================
+
+*idc-index* provides a command line interface (CLI) tool to simplify access to the functionality
+implemented via the Python API. The CLI tool is a wrapper around the Python API and provides a
+simple way to interact with the package.
+
+Once *idc-index* is installed, the CLI tool can be accessed by running the following command in the
+terminal.
+
+.. click:: idc_index.cli:idc
+  :prog: idc
+  :nested: full

docs/conf.py

@@ -15,6 +15,7 @@
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
+    "sphinx_click",
 ]
 
 source_suffix = [".rst", ".md"]

docs/index.md

@@ -29,6 +29,7 @@ starting a discussion in [IDC User forum](https://discourse.canceridc.dev/).
 :caption: API docs
 
 column_descriptions
+cli_tools.rst
 api/idc_index
 ```
 

idc_index/cli.py

@@ -19,8 +19,8 @@
 
 
 @click.group()
-def main():
-    """Idc is a command line client to help download data from Imaging Data Commons."""
+def idc():
+    """`idc` is a command line interface to the API functionality available in idc-index."""
 
 
 def set_log_level(log_level):
@@ -42,7 +42,7 @@ def set_log_level(log_level):
     logger_cli.setLevel(logging_level)
 
 
-@main.command()
+@idc.command()
 @click.option(
     "--download-dir",
     required=True,
@@ -199,7 +199,7 @@ def download_from_selection(
     )
 
 
-@main.command()
+@idc.command()
 @click.option(
     "--manifest-file",
     required=True,
@@ -291,7 +291,7 @@ def download_from_manifest(
     )
 
 
-@main.command()
+@idc.command()
 @click.argument(
     "generic_argument",
     type=str,
@@ -371,4 +371,4 @@ def check_and_download(column_name, item_ids, download_dir, kwarg_name):
 
 
 if __name__ == "__main__":
-    main()
+    idc()

pyproject.toml

@@ -42,6 +42,7 @@ dependencies = [
   "pyarrow",
   "requests",
   "s5cmd",
+  "sphinx-click",
   "tqdm"
 ]
 
@@ -63,7 +64,7 @@ docs = [
 ]
 
 [project.scripts]
-idc = 'idc_index.cli:main'
+idc = 'idc_index.cli:idc'
 
 [project.urls]
 Homepage = "https://github.com/ImagingDataCommons/idc-index"