docs: improve documentation structure

jjjermiah · Mar 16, 2024 · 1404c10 · 1404c10
1 parent 5ff0550
commit 1404c10
Show file tree

Hide file tree

Showing 15 changed files with 232 additions and 205 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -15,6 +15,11 @@
 copyright = "2023, Jermiah Joseph"
 author = "Jermiah Joseph"
 
+import nbiatoolkit
+
+# The full version, including alpha/beta/rc tags
+release: str = nbiatoolkit.__version__
+
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -28,6 +33,7 @@
     "sphinx.ext.viewcode",
     "sphinx_tabs.tabs",
     "sphinx_exec_code",
+    "sphinx.ext.autosectionlabel",
 ]
 autoapi_dirs = ["../src/nbiatoolkit"]
 

diff --git a/docs/tutorial_files/1_InitializeClient.rst → docs/getting_started/InitializeClient.rst b/docs/tutorial_files/1_InitializeClient.rst → docs/getting_started/InitializeClient.rst
@@ -118,7 +118,8 @@ If you would like to return the data as a pandas DataFrame, you can pass the
       Feel free to open an issue on the GitHub repository if you would like to see this feature added.
 
 
-Alternatively, you can set the return type for all methods by passing the `return_type` argument to the NBIAClient class.
+Alternatively, you can set the return type for all methods by passing the `return_type` argument when
+initializing the NBIAClient class.
 
 .. tabs::
 
@@ -141,7 +142,8 @@ Alternatively, you can set the return type for all methods by passing the `retur
 
 Logging
 ^^^^^^^
-The client can be initialized with a log level to control the verbosity of the logs. This is primarily intended for debugging and development purposes.
+The client can be initialized with a log level to control the verbosity of the logs. This is primarily
+intended for debugging and development purposes.
 The default log level is 'INFO' and the available log levels are `DEBUG`, `INFO`, `WARNING`, `ERROR`.
 
 .. tabs::

diff --git a/docs/getting_started/Installation.rst b/docs/getting_started/Installation.rst
@@ -0,0 +1,40 @@
+Installation
+____________
+
+`nbiatoolkit` is currently under development and is not guaranteed to be stable.
+Please refer to the `1.0.0 Stable Release Milestone <https://github.com/jjjermiah/nbia-toolkit/milestone/1>`_
+for the roadmap to the first stable release.
+
+PyPi Installation
+~~~~~~~~~~~~~~~~~
+
+The easiest way to install `nbiatoolkit` is to use `pip` to install it from the
+`Python Package Index (PyPi) <https://pypi.org/project/nbiatoolkit/>`_.
+
+.. code-block:: console
+
+    $ pip install nbiatoolkit
+
+***NOTE: It is recommended that you install the package in a conda or virtual environment.***
+
+Conda Installation
+~~~~~~~~~~~~~~~~~~
+
+Though the package is not available on conda, you can create a conda environment and install the package using pip:
+
+.. code-block:: console
+
+    $ conda create -n nbia python=3.12
+    $ conda activate nbia
+    $ pip install nbiatoolkit
+
+Virtual Environment Installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you prefer to use a virtual environment, you can create one and install the package using pip:
+
+.. code-block:: console
+
+    $ python3 -m venv nbia
+    $ source nbia/bin/activate
+    $ pip install nbiatoolkit
diff --git a/docs/markdowns/NBIA.md → docs/getting_started/NBIA.md b/docs/markdowns/NBIA.md → docs/getting_started/NBIA.md
diff --git a/docs/tutorial_files/logger.rst → docs/getting_started/logger.rst b/docs/tutorial_files/logger.rst → docs/getting_started/logger.rst
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,32 @@
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+.. toctree::
+    :caption: Getting started
+    :name: getting-started
+    :hidden:
+    :maxdepth: 2
+
+    getting_started/NBIA.md
+    getting_started/Installation.rst
+    getting_started/InitializeClient.rst
+    getting_started/logger.rst
+
+.. toctree::
+    :caption: Querying API
+    :name: querying-api
+    :hidden:
+    :maxdepth: 2
+
+    querying_api/ExploringCollections.rst
+    querying_api/ExploringModalities.rst
+
+.. toctree::
+    :caption: Project Info
+    :name: project-info
+    :hidden:
+    :maxdepth: 2
+
+    project_info/CONTRIBUTING.md
+    project_info/CHANGELOG.md
+    project_info/CONDUCT.md
diff --git a/docs/markdowns/Installation.md b/docs/markdowns/Installation.md
diff --git a/docs/markdowns/CHANGELOG.md → docs/project_info/CHANGELOG.md b/docs/markdowns/CHANGELOG.md → docs/project_info/CHANGELOG.md
@@ -1,4 +1,4 @@
-# CHANGELOG
+# Changelog
 
 
 
@@ -40,7 +40,7 @@
 
 * Merge pull request #123 from jjjermiah/development
 
-docs: Start building better documentation.
+docs: Start building better documentation.
 feat: Enhance logging functionality ([`5bb80c3`](https://github.com/jjjermiah/nbia-toolkit/commit/5bb80c3056fab8804ea789aa37702d9fd6741797))
 
 * Merge pull request #122 from jjjermiah/88-logger-functionality

diff --git a/docs/markdowns/CONDUCT.md → docs/project_info/CONDUCT.md b/docs/markdowns/CONDUCT.md → docs/project_info/CONDUCT.md
@@ -1,4 +1,4 @@
-# CODE OF CONDUCT
+# Code of Conduct
 
 ## Our Pledge
 

diff --git a/docs/markdowns/CONTRIBUTING.md → docs/project_info/CONTRIBUTING.md b/docs/markdowns/CONTRIBUTING.md → docs/project_info/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# CONTRIBUTING
+# Contributing
 
 Contributions are welcome, and they are greatly appreciated! Every little bit
 helps, and credit will always be given.

diff --git a/docs/querying_api/ExploringCollections.rst b/docs/querying_api/ExploringCollections.rst
@@ -0,0 +1,74 @@
+Collection Methods
+^^^^^^^^^^^^^^^^^^
+The simplest way to get a list of collections is to use the
+:meth:`nbiatoolkit.NBIAClient.getCollections` method.
+This method returns a list of all collections available in the NBIA database.
+
+The method has the following signature:
+
+.. automethod:: nbiatoolkit.NBIAClient.getCollections
+
+Passing no parameters to the method will return a list of all collections available in the NBIA database.
+Passing a `prefix` parameter will return a list of collections that match the prefix.
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. exec_code::
+
+         # --- hide: start ---
+         from nbiatoolkit import NBIAClient
+         from pprint import pprint as print
+         # --- hide: stop ---
+
+         client = NBIAClient(return_type = "dataframe")
+         collections_df = client.getCollections(prefix='TCGA')
+
+         print(f"The number of available collections is {len(collections_df)}")
+
+         print(collections_df)
+
+
+.. automethod:: nbiatoolkit.NBIAClient.getCollectionDescriptions
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. exec_code::
+
+         # --- hide: start ---
+         from nbiatoolkit import NBIAClient
+         from pprint import pprint as print
+         # --- hide: stop ---
+
+         with NBIAClient() as client:
+            desc = client.getCollectionDescriptions(collectionName = "TCGA-BLCA")[0]
+
+         print(desc['Description'])
+         print(desc['DescriptionURI'])
+         print(desc['LastUpdated'])
+
+
+
+.. automethod:: nbiatoolkit.NBIAClient.getCollectionPatientCount
+
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. exec_code::
+
+         # --- hide: start ---
+         from nbiatoolkit import NBIAClient
+         # --- hide: stop ---
+
+         with NBIAClient() as client:
+            counts_df = client.getCollectionPatientCount(
+               prefix = "TCGA",
+               return_type="dataframe"
+            )
+
+         print(counts_df)
diff --git a/docs/querying_api/ExploringModalities.rst b/docs/querying_api/ExploringModalities.rst
@@ -0,0 +1,62 @@
+
+
+Modality Methods
+^^^^^^^^^^^^^^^^^^
+The :meth:`getModalityValues` method can provide insight to the available modality types in the NBIA database.
+
+The method has the following signature:
+
+.. automethod:: nbiatoolkit.NBIAClient.getModalityValues
+
+Passing no parameters to the method will return a list of all modality types available in the NBIA database.
+Filtering by :code:`Collection` and :code:`BodyPartExamined` is also possible.
+The :code:`Counts` parameter can be set to :code:`True` to return the number of patients for each modality type.
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. tabs::
+
+         .. tab:: Default Query
+            .. exec_code::
+
+               # --- hide: start ---
+               from nbiatoolkit import NBIAClient
+               # --- hide: stop ---
+
+               with NBIAClient(return_type="dataframe") as client:
+                  modalities = client.getModalityValues()
+
+               print(modalities)
+
+         .. tab:: Filtered Query
+
+            .. exec_code::
+
+               # --- hide: start ---
+               from nbiatoolkit import NBIAClient
+               # --- hide: stop ---
+
+               with NBIAClient(return_type="dataframe") as client:
+                  modalities = client.getModalityValues(
+                     Collection = "TCGA-BLCA",
+                  )
+
+               print(modalities)
+
+         .. tab:: Counts Query
+
+            .. exec_code::
+
+               # --- hide: start ---
+               from nbiatoolkit import NBIAClient
+               # --- hide: stop ---
+
+               with NBIAClient(return_type="dataframe") as client:
+                  modalities = client.getModalityValues(
+                     Collection = "TCGA-BLCA",
+                     Counts = True
+                  )
+
+               print(modalities)