Some development and improvements.

.github/workflows/tests.yml

@@ -45,4 +45,14 @@ jobs:
           python-version: "3.11"
           cache: "pip"
       - run: "pip install -e '.[dev]'"
-      - run: pytest
+      - run: pytest
+  doctest:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - run: pip install -e '.[dev]'
+      - run: make -C docs doctest

.gitignore

@@ -175,4 +175,4 @@ src/bbprep.egg-info
 
 # Some folders get created by tests.
 docs/build
-
+.ruff_cache

README.rst

@@ -0,0 +1,59 @@
+:maintainers:
+  `andrewtarzia <https://github.com/andrewtarzia/>`_
+:documentation: https://bbprepared.readthedocs.io/en/latest/
+
+
+============
+Introduction
+============
+
+:mod:`bbprepared` or ``bbprep`` is a toolkit aimed at simplifying the
+preparation of your building blocks for
+`stk <https://stk.readthedocs.io/en/stable/>`_ construction and analysis.
+
+
+Installation
+============
+
+To get :mod:`.bbprepared`, you can install it with pip:
+
+.. code-block:: bash
+
+  pip install bbprepared
+
+Developer Setup
+---------------
+
+To develop with :mod:`bbprepared`, you can clone the repo and use
+`just <https://github.com/casey/just>`_ to setup the dev environment:
+
+.. code-block:: bash
+
+  just dev
+
+
+Examples
+========
+
+* See `Recipes` for usage and the code tests include additional examples.
+* See `gists <https://gist.github.com/andrewtarzia>`_ for usage.
+
+How To Cite
+===========
+
+If you use ``bbprepared`` please cite
+
+  https://github.com/andrewtarzia/bbprepared
+
+
+Acknowledgements
+================
+
+Funded by the European Union - Next Generation EU, Mission 4 Component 1
+CUP E13C22002930006 and the ERC under projects DYNAPOL.
+
+This work is a mixture of codes developed throughout my postdoc in the
+`Jelfs Group <http://www.jelfs-group.org/>`_, and the
+`Pavan Group <https://www.gmpavanlab.com/>`_, and during my time as a developer
+of `stk <https://stk.readthedocs.io/en/stable/>`_ and
+`stko <https://github.com/JelfsMaterialsGroup/stko>`_ with Lukas Turcani.

docs/source/_autosummary/bbprep.rst

@@ -52,6 +52,6 @@
    :template: module.rst
    :recursive:
 
-   bbprep.generators
-   bbprep.selectors
+   generators
+   selectors
 

docs/source/building_blocks.rst

@@ -0,0 +1,10 @@
+New building blocks
+===================
+
+New BuildingBlock classes to replace :class:`stk.BuildingBlock`. They may
+inherit or contain the ``stk`` class, depending on design considerations.
+
+.. toctree::
+  :maxdepth: 1
+
+  PanelBuildingBlock <_autosummary/bbprep.PanelBuildingBlock>

docs/source/conf.py

@@ -21,6 +21,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
+    "moldoc",
 ]
 
 autosummary_imported_members = True

docs/source/containers.rst

@@ -0,0 +1,24 @@
+Containers
+==========
+
+:class:`Ensemble` contain :class:`Conformer`, which contain
+:class:`stk.BuildingBlock`.
+
+.. toctree::
+  :maxdepth: 1
+
+  Conformer <_autosummary/bbprep.Conformer>
+  Ensemble <_autosummary/bbprep.Ensemble>
+
+Example:
+--------
+
+.. testcode:: containers-test
+
+    import stk
+    import bbprep
+
+    bb = stk.BuildingBlock(smiles="C1=CC=C(C=C1)C2=CC=CC=C2")
+    generator = bbprep.generators.ETKDG(num_confs=30)
+    ensemble = generator.generate_conformers(bb)
+    conformers = list(ensemble.yield_conformers())