diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder deleted file mode 100644 index e69de29..0000000 diff --git a/doc/source/_static/wrap_table.css b/doc/source/_static/wrap_table.css new file mode 100644 index 0000000..37c8935 --- /dev/null +++ b/doc/source/_static/wrap_table.css @@ -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; +} diff --git a/doc/source/api/diffpy.cmi.example_package.rst b/doc/source/api/diffpy.cmi.example_package.rst deleted file mode 100644 index 837c713..0000000 --- a/doc/source/api/diffpy.cmi.example_package.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _example_package documentation: - -|title| -======= - -.. |title| replace:: diffpy.cmi.example_package package - -.. automodule:: diffpy.cmi.example_package - :members: - :undoc-members: - :show-inheritance: - -|foo| ------ - -.. |foo| replace:: diffpy.cmi.example_package.foo module - -.. automodule:: diffpy.cmi.example_package.foo - :members: - :undoc-members: - :show-inheritance: - -|bar| ------ - -.. |bar| replace:: diffpy.cmi.example_package.bar module - -.. automodule:: diffpy.cmi.example_package.foo - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/source/api/diffpy.cmi.rst b/doc/source/api/diffpy.cmi.rst index 362d3d5..3f3b7c1 100644 --- a/doc/source/api/diffpy.cmi.rst +++ b/doc/source/api/diffpy.cmi.rst @@ -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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 1f5bd85..bfa13cc 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst index 68a04b8..374b8b7 100644 --- a/doc/source/getting-started.rst +++ b/doc/source/getting-started.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 `. - -.. 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 -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 -env python=3.13 \ - --file requirements/tests.txt \ - --file requirements/conda.txt \ - --file requirements/build.txt - - # Activate the environment - conda activate _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... diff --git a/doc/source/img/diffpycmi_screenshot.png b/doc/source/img/diffpycmi_screenshot.png new file mode 100644 index 0000000..b491920 Binary files /dev/null and b/doc/source/img/diffpycmi_screenshot.png differ diff --git a/doc/source/img/scikit-package-logo-text.png b/doc/source/img/scikit-package-logo-text.png deleted file mode 100644 index 823178d..0000000 Binary files a/doc/source/img/scikit-package-logo-text.png and /dev/null differ diff --git a/doc/source/index.rst b/doc/source/index.rst index 84c46cb..e8faac3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 ` page. ======= @@ -44,6 +50,7 @@ Table of contents :maxdepth: 2 getting-started + Tutorials Package API release license diff --git a/doc/source/snippets/diffpy_libraries.rst b/doc/source/snippets/diffpy_libraries.rst new file mode 100644 index 0000000..20ba950 --- /dev/null +++ b/doc/source/snippets/diffpy_libraries.rst @@ -0,0 +1,27 @@ +.. list-table:: + :widths: 3 10 1 + :header-rows: 1 + :class: wrap-text + + + * - Package + - Description + - Docs + * - `diffpy.srfit `_ + - Setup and control of general fitting problems. + - `doc `_ + * - `diffpy.srreal `_ + - Calculators for PDF, bond valence sum, and other quantities based on atom pair interaction. + - `doc `_ + * - `diffpy.structure `_ + - Crystal structure container and parsers for structure formats. + - `doc `_ + * - `diffpy.utils `_ + - General purpose utilities for the diffpy libraries. + - `doc `_ + * - `pyobjcryst `_ + - Python bindings to ObjCryst++, the Object-Oriented Crystallographic Library. + - `doc `_ + * - `libdiffpy `_ + - C++ library for calculation of PDF and other real-space quantities. + - `doc `_ diff --git a/doc/source/snippets/example-table.rst b/doc/source/snippets/example-table.rst deleted file mode 100644 index 7c4c11d..0000000 --- a/doc/source/snippets/example-table.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. list-table:: 5 levels of reusing/sharing code - :widths: 5 15 40 40 - :header-rows: 1 - - * - Level - - Name - - Scope - - How to setup - * - 1 - - ``function`` - - Reuse code in the single file. - - See Level 1 tutorial - * - 2 - - ``module`` - - Reuse code across files. - - See Level 2 tutorial - * - 3 - - ``workspace`` - - Reuse code across project folders. - - ``package create workspace`` - * - 4 - - ``system`` - - Reuse code across any files in the computer. - - ``package create system`` - * - 5 - - ``public`` - - Share code as publicly installable package. - - ``package create public`` diff --git a/doc/source/snippets/external_libraries.rst b/doc/source/snippets/external_libraries.rst new file mode 100644 index 0000000..7936e84 --- /dev/null +++ b/doc/source/snippets/external_libraries.rst @@ -0,0 +1,21 @@ +.. list-table:: + :widths: 3 10 1 + :header-rows: 1 + :class: wrap-text + + + * - Package + - Description + - Docs + * - `srfit-sasview `_ + - Selected modules from SasView, the Small Angle Scattering Analysis Software Package. + - `doc `_ + * - `periodictable `_ + - Extensible periodic table of the elements with support for mass, density, and X-ray/neutron scattering information. + - `doc `_ + * - `libobjcryst `_ + - ObjCryst++, crystallographic library for C++ re-packaged for installation as a shared library. + - `doc `_ + * - `cxxtest `_ + - Testing framework for C++. + - `doc `_ diff --git a/doc/source/tutorials/index.rst b/doc/source/tutorials/index.rst new file mode 100644 index 0000000..42fef8e --- /dev/null +++ b/doc/source/tutorials/index.rst @@ -0,0 +1,4 @@ +Tutorials +========= + +Examples usage of ``diffpy.cmi`` can be found at `this GitHub repo `_. Tutorials coming soon... diff --git a/news/lightweight-docs.rst b/news/lightweight-docs.rst new file mode 100644 index 0000000..50fb9e1 --- /dev/null +++ b/news/lightweight-docs.rst @@ -0,0 +1,23 @@ +**Added:** + +* Add light-weight documentation migrated from old diffpy-CMI documentation. + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +*