Eac/reredoc (#13)

* updated docs

* updating docs

docs/index.rst

@@ -1,10 +1,14 @@
-=========================================================================
+#########################################################################
 rail_projects: a toolkit for managing `RAIL`-based data analysis projects
-=========================================================================
+#########################################################################
+
+***********
+Description
+***********
+
+`rail_projects` is a tool-kit to manage RAIL-baseed data analysis
+projects. 
 
-----
-RAIL
-----
 
 RAIL is a flexible open-source software library providing tools to produce at-scale photometric redshift data products, including uncertainties and summary statistics, and stress-test them under realistically complex systematics.
 
@@ -19,15 +23,6 @@ See `guideline for citing RAIL
 guidance on citing RAIL and the underlying algorithms.
 
 
----------------
-`rail_projects`
----------------
-
-`rail_projects` is a tool-kit to manage RAIL-baseed data analysis
-projects. 
-
-
-
 .. toctree::
    :maxdepth: 1
    :caption: Getting Started
@@ -39,9 +34,10 @@ projects.
    :maxdepth: 1
    :caption: Concepts
 
-   source/rail_project	     
+   source/rail_project
+   source/pipelines
+   source/flavors
    source/components
-   source/factories
 
 .. toctree::
    :maxdepth: 1

docs/source/components.rst

@@ -1,8 +1,39 @@
+************************************
+components, factories, and libraries
+************************************
+
+**components**
+
+Doing series of related studies using RAIL requires many pieces, such
+as the lists of algorithms available, sets of analysis pipelines we
+might run, types of plots we might make, types of data we can extract
+from out analyses, references to particular files or sets of files we
+want to use for out analysses, and so for.   In general we call these
+analysis components, and we need ways to keep track of them.
+
+We have implemented interfaces to allow us to read and write
+components to yaml files.  
+
+
+**factories**
+
+A Factory is a python class that can make specific type or types of
+components, assign names to each, and keep track of what it has made.
+
+
+**libraries**:
+
+A library is the collection of all the components that have been
+loaded.  Typically there are collected into one, or a few yaml
+configuration files to allow users to load them easily.
+
+
 *******************
-Analysis components
+Analysis Components
 *******************
 
 
+=========================
 Analysis component basics
 =========================
 
@@ -16,7 +47,7 @@ The basic interface to analysis components is the :py:class:`rail.projects.confi
 4. mechansims to read/write the component to yaml, including the ``yaml_tag`` class member defining the yaml tag that marks a block of yaml as defining an object of a particular type of component.
 
 
-
+============================
 File and Catalog definitions
 ============================
 
@@ -76,7 +107,7 @@ When called with a dict such as `{flavor: baseline, healpix : [3433, 3344]}` the
 `a_file/3344/baseline_data.hdf5`
 
 
-
+=====================
 Algorithm definitions
 =====================
 
@@ -178,7 +209,7 @@ Subsample
 :py:class:`rail.projects.subsample_factor.RailSubsample` just provides parameters such as the random number seed and number of object requested need by subsamplers.
 
 
-
+================
 Plot definitions
 ================
 
@@ -201,6 +232,7 @@ types of plots.
 
 
 
+===========================
 Plotting dataset defintions
 ===========================
 
@@ -227,7 +259,7 @@ Project
 
 
 
-
+======================
 Plot Group definitions
 ======================
 
@@ -236,3 +268,100 @@ PlotGroup
 ---------
 
 :py:class:`rail.plotting.plot_group.RailPlotGroup` defines a set of plots to make by iterating over a `PlotterList` and a `DatasetList`.
+
+
+
+*********
+Factories
+*********
+
+
+==============
+Factory basics
+==============
+
+A Factory is a python class that can make specific type or types of
+components, assign names to each, and keep track of what it has made.
+
+The basic interface to Factories is the :py:class:`rail.projects.factory_mixin.FactoryMixin` class, which defines a few things,
+
+1. The "Factory pattern" of having a singleton instance of the factory that manages all the components of particular types, and class methods to interact with the instance.
+2. A `client_classes` class member object specifying what types of components a particular factory manages.
+3. Methods to add objects to a factory, and reset the factory contents.
+4. Interfaces for reading and writing objects to and from yaml files.
+5. Type validation, to ensure that only the correct types of objects are created or added to factories.
+
+
+==================
+Specific Factories
+==================
+
+.. list-table:: Factories
+   :widths: 40 10 10 40
+   :header-rows: 1
+
+   * - Factory Class
+     - Yaml Tag
+     - Example Yaml File
+     - Managed Classes
+   * - :py:class:`rail.projects.project_file_factory.RailProjectFileFactory`
+     - `Files`
+     - `tests/ci_project_files.yaml <https://github.com/LSSTDESC/rail_projects/blob/main/tests/ci_project_files.yaml>`_
+     - `RailProjectFileInstance`, `RailProjectFileTemplate`
+   * - :py:class:`rail.projects.catalog_factory.RailCatalogFactory`
+     - `Catalogs`
+     - `tests/ci_catalogs.yaml <https://github.com/LSSTDESC/rail_projects/blob/main/tests/ci_catalogs.yaml>`_       
+     - `RailProjectCatalogInstance`, `RailProjectCatalogTemplate`
+   * - :py:class:`rail.projects.subsample_factory.RailSubsampleFactory`
+     - `Subsamples`
+     - `tests/ci_subsamples.yaml <https://github.com/LSSTDESC/rail_projects/blob/main/tests/ci_subsamples.yaml>`_       
+     - `RailSubsample`
+   * - :py:class:`rail.projects.selection_factory.RailSelectionFactory`
+     - `Selections`
+     - `tests/ci_selections.yaml <https://github.com/LSSTDESC/rail_projects/blob/main/tests/ci_selections.yaml>`_
+     - `RailSelection`
+   * - :py:class:`rail.projects.algorithm_factory.RailAlgorithmFactory`
+     - `PZAlgorithms`
+     - `tests/ci_algorithms.yaml <https://github.com/LSSTDESC/rail_projects/blob/main/tests/ci_algorithms.yaml>`_
+     - `RailPZAlgorithmHolder`
+   * - 
+     - `Classifiers`
+     -
+     - `RailClassificationAlgorithmHolder`
+   * - 
+     - `Summarizers`
+     -
+     - `RailSummarizerAlgorithmHolder`
+   * - 
+     - `SpecSelections`
+     -
+     - `RailSpecSelectionAlgorithmHolder`
+   * - 
+     - `ErrorModels`
+     -
+     - `RailErrorModelAlgorithmHolder`
+   * - 
+     - `Subsamplers`
+     -
+     - `RailSubsamplerAlgorithmHolder`
+   * - 
+     - `Reducers`
+     -
+     - `RailReducerAlgorithmHolder`
+   * - :py:class:`rail.projects.pipeline_factory.RailPipelineFactory`
+     - `Pipelines`
+     - `tests/ci_pipelines.yaml <https://github.com/LSSTDESC/rail_projects/blob/main/tests/ci_pipelines.yaml>`_
+     - `RailPipelineTemplate`, `RailPipelineInstance`
+   * - :py:class:`rail.plotting.plotter_factory.RailPlotterFactory`
+     - `Plots`
+     - `tests/ci_plots.yaml <https://github.com/LSSTDESC/rail_projects/blob/main/tests/ci_plots.yaml>`_
+     - `RailPlotter`, `RailPlotterList`
+   * - :py:class:`rail.plotting.dataset_factory.RailDatasetFactory`
+     - `Data`
+     - `tests/ci_datasets.yaml <https://github.com/LSSTDESC/rail_projects/blob/main/tests/ci_datasets.yaml>`_
+     - `RailDatasetHolder`, `RailDatasetListHolder`, `RailProjectHolder`
+   * - :py:class:`rail.plotting.plot_group_factory.RailPlotGroupFactory`
+     - `PlotGroups`
+     - `tests/ci_plot_groups.yaml <https://github.com/LSSTDESC/rail_projects/blob/main/tests/ci_plot_groups.yaml>`_
+     - `RailPlotGroup`
+

docs/source/contributing.rst

@@ -5,7 +5,7 @@ Contribution Overview
 RAIL is a constellation of multiple packages developed publicly on GitHub and 
 welcomes all interested developers, regardless of DESC membership or LSST data rights.
 
-
+====================
 Contributing to RAIL
 ====================
 
@@ -14,9 +14,9 @@ algorithms or similar analysis tools, please visit
 `contributing to RAIL <https://rail-hub.readthedocs.io/en/latest/source/contributing.html>`_
 
 
----------------------------------
+=================================
 Contributing to ``rail_projects``
----------------------------------
+=================================
 
 If you're interested in contributing to `rail_projects`, but don't know where to start, take a look 
 at the
@@ -36,13 +36,16 @@ Those without data rights who wish to gain access to the Slack channel should
 the team leads initiate the process for adding a DESC External Collaborator.
 
 
+====================
 Where to contribute:
 ====================
 
 In all cases, begin by following the developer installation instructions 
 :ref:`Developer Installation` and follow the contribution workflow instructions below.
 
 
+
+=====================
 Contribution workflow
 =====================
 
@@ -113,27 +116,28 @@ It is also considered good practice to make suggestions for optional improvement
 such as adding a one-line comment before a clever block of code or including a 
 demonstration of new functionality in the example notebooks.
 
+
 Naming conventions
-==================
+------------------
 
 We follow the `pep8 <https://peps.python.org/pep-0008/#descriptive-naming-styles>`_ 
 recommendations for naming new modules.
 
 
 Modules
--------
+^^^^^^^
 
 Modules should use all lowercase, with underscores where it aids the readability
 of the module name. 
 
 
 Classes
--------
+^^^^^^^
 
 Python classes and so should use the CapWords convention.
 
 
-
+==================
 Contribution Types
 ==================
 

docs/source/fix_an_issue.rst

@@ -1,6 +1,6 @@
-************
+============
 Fix an Issue
-************
+============
 
 The typical workflow for fixing a specific issue will look something like the following: