Merge pull request #23 from cadenmyers13/lightweight-docs

docs: Migrate over a lightweight version of documentation

Author: sbillinge

doc/source/_static/.placeholder

@@ -0,0 +1,8 @@
+/* Force all Sphinx docutils tables to wrap text in cells (RTD theme & general) */
+.rst-content table.docutils td,
+.rst-content table.docutils th,
+.wy-table-responsive table td,
+.wy-table-responsive table th {
+  white-space: normal !important;
+  word-break: normal !important;
+}

doc/source/_static/wrap_table.css

@@ -3,28 +3,16 @@
 |title|
 =======
 
-.. |title| replace:: diffpy.cmi package
+.. |title| replace:: diffpy.cmi Contents
 
-.. automodule:: diffpy.cmi
-    :members:
-    :undoc-members:
-    :show-inheritance:
+``diffpy.cmi`` includes Python and C++ libraries developed by the DiffPy team as well as external libraries necessary for functionality.
 
-Subpackages
------------
+Libraries developed by the DiffPy team
+--------------------------------------
 
-.. toctree::
-   diffpy.cmi.example_package
+.. include:: ../snippets/diffpy_libraries.rst
 
-Submodules
-----------
+External Libraries
+------------------
 
-|module|
---------
-
-.. |module| replace:: diffpy.cmi.example_submodule module
-
-.. automodule:: diffpy.cmi.example_submodule
-    :members:
-    :undoc-members:
-    :show-inheritance:
+.. include:: ../snippets/external_libraries.rst

doc/source/api/diffpy.cmi.example_package.rst

@@ -172,7 +172,8 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ["_static"]
+html_css_files = ["wrap_table.css"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

doc/source/api/diffpy.cmi.rst

@@ -8,72 +8,4 @@
 Getting started
 ================
 
-Here are some example templates provided to help you get started with writing your documentation. You can use these templates to create your own documentation.
-
-Reuse ``.rst`` files across multiple pages
-------------------------------------------
-
-Here is how you can reuse a reusable block of ``.rst`` files across multiple pages:
-
-.. include:: snippets/example-table.rst
-
-.. warning::
-
-    Ensure that the ``.rst`` file you are including is not too long. If it is too long, it may be better to split it into multiple files and include them separately.
-
-Refer to a specific section in the documentation
-------------------------------------------------
-
-You can use the ``ref`` tag to refer to a specific section in the documentation. For example, you can refer to the section below using the ``:ref:`` tag as shown :ref:`here <attach-image>`.
-
-.. note::
-
-    Please check the raw ``.rst`` file of this page to see the exact use of the ``:ref:`` tag.
-
-Embed your code snippets in the documentation
----------------------------------------------
-
-Here is how you can write a block of code in the documentation. You can use the ``code-block`` directive to write a block of code in the documentation. For example, you can write a block of code as shown below:
-
-.. code-block:: bash
-
-    # Create a new environment, without build dependencies (pure Python package)
-    conda create -n <package_name>-env python=3.13 \
-        --file requirements/tests.txt \
-        --file requirements/conda.txt
-
-    # Create a new environment, with build dependencies (non-pure Python package)
-    conda create -n <package_name>-env python=3.13 \
-        --file requirements/tests.txt \
-        --file requirements/conda.txt \
-        --file requirements/build.txt
-
-    # Activate the environment
-    conda activate <package_name>_env
-
-    # Install your package locally
-    # `--no-deps` to NOT install packages again from `requirements.pip.txt`
-    pip install -e . --no-deps
-
-    # Run pytest locally
-    pytest
-
-    # ... run example tutorials
-
-.. _attach-image:
-
-Attach an image to the documentation
-------------------------------------
-
-Here is how you attach an image to the documentation. The ``/doc/source/img/scikit-package-logo-text.png`` example image is provided in the template.
-
-.. image:: ./img/scikit-package-logo-text.png
-    :alt: codecov-in-pr-comment
-    :width: 400px
-    :align: center
-
-
-Other useful directives
------------------------
-
-Here is how you can do menu selection  :menuselection:`Admin --> Settings` and display labels for buttons like :guilabel:`Privacy level`.
+Coming soon...

doc/source/conf.py

@@ -3,18 +3,24 @@
 #######
 
 .. |title| replace:: diffpy.cmi documentation
+| Software version |release|
+| Last updated |today|.
 
 ``diffpy.cmi`` - Complex modeling infrastructure: a modular framework for multi-modal modeling of scientific data.
 
-| Software version |release|
-| Last updated |today|.
+DiffPy.CMI is our complex modeling framework. It is a highly flexible library of Python modules for robust modeling of nanostructures in crystals, nanomaterials, and amorphous materials.
+
+The software provides functionality for storage and manipulation of structure data and calculation of structure-based quantities, such as PDF, SAS, bond valence sums, atom overlaps, bond lengths, and coordinations. Most importantly the diffpy.cmi package contains a fitting framework for combining multiple experimental inputs in a single optimization problem.
+
+.. image:: ./img/diffpycmi_screenshot.png
+    :alt: codecov-in-pr-comment
+    :width: 400px
+    :align: center
 
 ===============
 Getting started
 ===============
 
-Welcome to the ``diffpy.cmi`` documentation!
-
 To get started, please visit the :ref:`Getting started <getting-started>` page.
 
 =======
@@ -44,6 +50,7 @@ Table of contents
    :maxdepth: 2
 
    getting-started
+   Tutorials <tutorials/index>
    Package API <api/diffpy.cmi>
    release
    license

doc/source/getting-started.rst

@@ -0,0 +1,27 @@
+.. list-table::
+   :widths: 3 10 1
+   :header-rows: 1
+   :class: wrap-text
+
+
+   * - Package
+     - Description
+     - Docs
+   * - `diffpy.srfit <https://github.com/diffpy/diffpy.srfit>`_
+     - Setup and control of general fitting problems.
+     - `doc <https://www.diffpy.org/diffpy.srfit/>`_
+   * - `diffpy.srreal <https://github.com/diffpy/diffpy.srreal>`_
+     - Calculators for PDF, bond valence sum, and other quantities based on atom pair interaction.
+     - `doc <https://www.diffpy.org/diffpy.srreal/>`_
+   * - `diffpy.structure <https://github.com/diffpy/diffpy.structure>`_
+     - Crystal structure container and parsers for structure formats.
+     - `doc <https://www.diffpy.org/diffpy.structure/>`_
+   * - `diffpy.utils <https://github.com/diffpy/diffpy.utils>`_
+     - General purpose utilities for the diffpy libraries.
+     - `doc <https://www.diffpy.org/diffpy.utils/>`_
+   * - `pyobjcryst <https://github.com/diffpy/pyobjcryst>`_
+     - Python bindings to ObjCryst++, the Object-Oriented Crystallographic Library.
+     - `doc <https://www.diffpy.org/pyobjcryst/>`_
+   * - `libdiffpy <https://github.com/diffpy/libdiffpy>`_
+     - C++ library for calculation of PDF and other real-space quantities.
+     - `doc <https://www.diffpy.org/libdiffpy/>`_