Split docs into separate files

docs/api.rst

@@ -1,6 +1,8 @@
 API
 ===
 
+Documentation for directly using the Python functions.
+
 .. automodule:: tbpcxr
     :members:
 

docs/development.rst

@@ -0,0 +1,39 @@
+Development
+===========
+
+To setup for development:
+
+.. code-block:: bash
+
+  python -m pip install --editable .[dev]
+
+Git LFS
+=======
+
+Git `Large File Storage <https://git-lfs.github.com>`_ (LFS) is used to store larger files in the repository such as
+test images, trained models, and other data ( i.e. not text based code ). Before the repository is cloned, git lfs must
+be installed on the system and set up on the users account. The `tool's documentation <https://git-lfs.github.com>`_
+provides details on installation, set up, and usage that is not duplicated here. Once set up the git usage is usually
+transparent with operation such as cloning, adding files, and changing branches.
+
+The ".gitattributes" configuration file automatically places files in the directories "test/data" and "my_pkg/data" to
+be stored in Git LFS.
+
+
+Linting
+=======
+
+The linting processes are configured and run with `pre-commit <https://pre-commit.com>`_. Using pre-commit provides
+a single file ( ".pre-commit-config.yaml" ) configuration for both execution of CI and local git pre-commit hooks. The
+"pre-commit" package does not need to be installed in the projects venv. One initialized for the project, pre-commit
+will manage the versions of the tools in a separate environment, that is automatically managed.
+
+The following is the `quick start guide <https://pre-commit.com/#quick-start>`_.
+
+The linting process uses both `Black <https://black.readthedocs.io/en/stable/>`_  and
+`flake8 <https://flake8.pycqa.org/en/latest/>`_ to ensure uncompromising code formatting and some programmatic problems.
+The Black must be used to auto format new code before committing:
+
+.. code:: bash
+
+    python -m black .

docs/example.rst

@@ -0,0 +1,36 @@
+
+Example
+=======
+
+To classify a single image:
+
+.. code-block:: python
+
+ from tbpcxr.model import Model
+ from tbpcxr.utilities import read_dcm
+
+ outlier_model = Model.load_outlier_pcamodel()
+
+ img = read_dcm(path_to_file)
+
+ arr = outlier_model.to_observations([img])
+
+ if outlier_model.outlier_predictor(arr)[0] == -1:
+    print("{} is an outlier".format(path_to_file))
+
+
+Multiple images can efficiently be processed by using Python `map` function, which
+
+.. code-block:: python
+
+ from tbpcxr.model import Model
+ from tbpcxr.utilities import read_dcm
+
+ outlier_model = Model.load_outlier_pcamodel()
+
+ arr = outlier_model.to_observations(map(read_dcm, image_file_list))
+
+ results = outlier_model.outlier_predictor(arr)
+
+ for fn in [fn for fn, o in zip(image_file_list, results) if o == -1]:
+    print("{} is an outlier".format(fn))

docs/index.rst

@@ -3,79 +3,28 @@
 Welcome to tbpcxr's documentation!
 =====================================
 
-.. include:: ../README.rst
-
-
-Example
--------
-
-To process a single image:
-
-.. code-block:: python
-
- from tbpcxr.model import Model
- from tbpcxr.utilities import read_dcm
-
- outlier_model = Model.load_outlier_pcamodel()
-
- img = read_dcm(path_to_file)
-
- arr = outlier_model.to_observations([img])
-
- if outlier_model.outlier_predictor(arr)[0] == -1:
-    print("{} is an outlier".format(path_to_file))
-
-
-Multiple images can efficiently be processed by using Python `map` function, which
-
-.. code-block:: python
-
- from tbpcxr.model import Model
- from tbpcxr.utilities import read_dcm
-
- outlier_model = Model.load_outlier_pcamodel()
-
- arr = outlier_model.to_observations(map(read_dcm, image_file_list))
-
- results = outlier_model.outlier_predictor(arr)
-
- for fn in [fn for fn, o in zip(image_file_list, results) if o == -1]:
-    print("{} is an outlier".format(fn))
-
-
-API Reference
--------------
-
-Documentation for directly using the Python functions.
+Table of Contents
+=================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
+   example
    api
+   development
 
+Indices and tables
+==================
 
-Development
------------
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
 
-The `Git Large File Storage`_ (LFS) is required to retrieve and store images and data files in the tbp-cxr-outlier
-repository. The Git LFS client needs to be installed and initialized to automatically perform these operations.
 
-The required packages for development are specified in `requirements-dev.txt`. The tbp-cxr-outlier project must be
-install for it to function properly. Specifically, because semantic versioning is done with `setuptools-scm` it must be
-installed. To setup for development::
+.. include:: ../README.rst
+
 
-  python -m pip install requirements-dev.txt
-  python -m pip install --editable .
 
-New contributions must come from pull requests on GitHub. New features should start as local branch with a name
-starting with "feature-" followed by a description. After changes are made check the passing of flake8 and the tests
-without warnings or errors::
 
-  python -m flake8
-  python -m pytest
 
-Since the repository is internal, the feature branch needs to be
-pushed to the *upstream* repository. Next a pull request is made against master, where the CI will automatically run
-flake8, pytest and sphinx. When merging the branch with rebased onto the origin, and the feature branch is deleted.
 
-.. _Git Large File Storage : https://git-lfs.github.com