Docs new

.github/workflows/python-app.yml

@@ -13,7 +13,7 @@ jobs:
   build:
 
     runs-on: ubuntu-latest
-    
+
     strategy:
       matrix:
        py_version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
@@ -30,7 +30,7 @@ jobs:
         pip install --upgrade .
         pip install git+https://github.com/pckroon/pysmiles.git
         pip install -r requirements-tests.txt
-        
+
     - name: Run pytest with codecoverage
       run:  pytest --cov cgsmiles --cov-report=xml
 #    - name: Upload coverage codecov   
@@ -55,6 +55,31 @@ jobs:
         pip install --upgrade setuptools pip
         pip install --upgrade .
         pip install -r requirements-tests.txt
-    - name: Run pylint 
+    - name: Run pylint
       run: |
          pylint --disable=fixme --fail-under=8.0 cgsmiles
+
+  docs:
+      runs-on: ubuntu-latest
+
+      steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3
+        uses: actions/setup-python@v5
+        with:
+           python-version: '3.x'
+           cache: pip
+           cache-dependency-path: |
+             **/setup.cfg
+             **/requirements-*.txt
+             **/pyproject.toml
+      - name: Install dependencies
+        run: |
+          pip install --upgrade setuptools pip
+          pip install --upgrade .
+          pip install -r requirements-docs.txt
+
+      - name: Run docs
+        run: |
+          mkdir -p docs/source/_static
+          sphinx-build -E -b html docs/source/ docs/build/html

.readthedocs.yml

@@ -0,0 +1,29 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3"
+
+formats:
+  - pdf
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: html
+  fail_on_warning: true
+  configuration: docs/source/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+ install:
+   - method: pip
+     path: .
+   - requirements: requirements-docs.txt

README.rst

@@ -0,0 +1,92 @@
+================================
+Coarse-Grained SMILES (CGsmiles)
+================================
+
+Overview
+========
+
+The CGSmiles line notation encodes arbitrary resolutions of molecules and
+defines the conversion between these resolutions unambiguously. For example,
+in coarse-grained (CG) simulations multiple atoms are represented as one large
+pseudo-atom often called bead. The conversion from the atomic resolution to
+the CG resolution can be described using the CGSmiles notation. In the
+`Martini 3 force field <https://cgmartini.nl>`__, Benzene is represented
+as three particles. The CGSmiles string would be:
+
+.. code::
+
+    "{[#TC5]1[#TC5][#TC5]1}.{#TC5=[$]cc[$]}"
+
+Additionally, multiple resolutions may be layered together so that a hirachical
+description between one or more CG resolutions becomes possible. Especially,
+expressing large polymeric molecules becomes simpler when using multiple
+resolution. For instance consider the copolymer
+`Styreic-Melic Acid <https://en.wikipedia.org/wiki/Styrene_maleic_anhydride>`__.
+It is an almost perfectly alternating polymer of maleic anhydrade and styrene.
+In CGSmiles, we can thus write 100 repeat units of this polymer by using three
+resolutions each contained in curly braces:
+
+.. code::
+
+    "{[#SMA]|100}.{#SMA=[#PS][#MAH]}.{#PS=[>]CC[<]c1ccccc1,#MHA=[<]C1C(=O)CC(=O)C1[>]}"
+
+The CGSmiles Python package is created around this notation to read, write, and
+further process the resulting graphs. Reading and resolving provides the all the
+molecule information in form of `NetworkX graphs <https://networkx.org>`__,
+providing an easy way to interface with other python libraries.
+
+There are a number of other packages and libraries, which use CGSmiles. They are
+mostly used for coarse-grained modelling with the Martini force field or atomic
+resolution molecular dynamics simulations. More informtion about the syntax and
+the different use cases can be found in this documentation. If you are here from
+one of the packages using CGSmiles check out the GettingStarted section to learn
+the syntax.
+
+Examples
+========
+
+The CGSmiles python package is designed to read and resolve these smiles
+into networkx graphs that can be used for further tasks, for example drawing
+the relation between two resolutions (i.e. the mapping).
+
+Martini 3 Benzene
+
+.. code:: python
+
+    import cgsmiles
+    from cgsmiles.drawing import draw_molecule
+
+    # Martini 3 Benzene
+    cgsmiles_str = "{[#TC5]1[#TC5][#TC5]1}.{#TC5=[$]cc[$]}"
+
+    # Resolve molecule into networkx graphs
+    res_graph, mol_graph = cgsmiles.MoleculeResolver.from_string(cgsmiles_str).resolve()
+
+    # Draw molecule at different resolutions
+    ax, pos = draw_molecule(mol_graph)
+
+Resources
+=========
+
+- here go some resources
+
+Related Tools
+=============
+
+- `pysmiles <https://github.com/pckroon/pysmiles>`__:
+  Lightweight python library for reading and writing SMILES. CGSmiles runs
+  pysmiles in the background for interpreting atomic resolution fragments.
+
+- `polyply <https://github.com/marrink-lab/polyply_1.0>`__:
+  Generate topology files and coordinates for molecular dynamics (MD)
+  from CGSmiles notation. It takes CGSmiles as input to generate all-atom or
+  coarse-grained topologies and input parameters.
+
+- `fast_forward <https://github.com/fgrunewald/fast_forward>`__:
+  Forward map molecular dynamics trajectories from a high to lower resolution using
+  CGSmiles.
+
+Citation
+========
+
+When using **cgsmiles** to for your publication, please:

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = CGSmiles
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/api/cgsmiles.cgsmiles_utils.rst

@@ -0,0 +1,5 @@
+cgsmiles.cgsmiles\_utils module
+===============================
+
+.. automodule:: cgsmiles.cgsmiles_utils
+   :members:

docs/source/api/cgsmiles.dialects.rst

@@ -0,0 +1,5 @@
+cgsmiles.dialects module
+========================
+
+.. automodule:: cgsmiles.dialects
+   :members:

docs/source/api/cgsmiles.drawing.rst

@@ -0,0 +1,5 @@
+cgsmiles.drawing module
+=======================
+
+.. automodule:: cgsmiles.drawing
+   :members:

docs/source/api/cgsmiles.drawing_utils.rst

@@ -0,0 +1,5 @@
+cgsmiles.drawing\_utils module
+==============================
+
+.. automodule:: cgsmiles.drawing_utils
+   :members:

docs/source/api/cgsmiles.graph_layout.rst

@@ -0,0 +1,5 @@
+cgsmiles.graph\_layout module
+=============================
+
+.. automodule:: cgsmiles.graph_layout
+   :members:

docs/source/api/cgsmiles.graph_layout_utils.rst

@@ -0,0 +1,5 @@
+cgsmiles.graph\_layout\_utils module
+====================================
+
+.. automodule:: cgsmiles.graph_layout_utils
+   :members:

docs/source/api/cgsmiles.graph_utils.rst

@@ -0,0 +1,5 @@
+cgsmiles.graph\_utils module
+============================
+
+.. automodule:: cgsmiles.graph_utils
+   :members:

docs/source/api/cgsmiles.linalg_functions.rst

@@ -0,0 +1,5 @@
+cgsmiles.linalg\_functions module
+=================================
+
+.. automodule:: cgsmiles.linalg_functions
+   :members:

docs/source/api/cgsmiles.pysmiles_utils.rst

@@ -0,0 +1,5 @@
+cgsmiles.pysmiles\_utils module
+===============================
+
+.. automodule:: cgsmiles.pysmiles_utils
+   :members:

docs/source/api/cgsmiles.read_cgsmiles.rst

@@ -0,0 +1,5 @@
+cgsmiles.read\_cgsmiles module
+==============================
+
+.. automodule:: cgsmiles.read_cgsmiles
+   :members:

docs/source/api/cgsmiles.read_fragments.rst

@@ -0,0 +1,5 @@
+cgsmiles.read\_fragments module
+===============================
+
+.. automodule:: cgsmiles.read_fragments
+   :members:

docs/source/api/cgsmiles.resolve.rst

@@ -0,0 +1,5 @@
+cgsmiles.resolve module
+=======================
+
+.. automodule:: cgsmiles.resolve
+   :members:

docs/source/api/cgsmiles.rst

@@ -0,0 +1,29 @@
+cgsmiles package
+================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   cgsmiles.cgsmiles_utils
+   cgsmiles.dialects
+   cgsmiles.drawing
+   cgsmiles.drawing_utils
+   cgsmiles.graph_layout
+   cgsmiles.graph_layout_utils
+   cgsmiles.graph_utils
+   cgsmiles.linalg_functions
+   cgsmiles.pysmiles_utils
+   cgsmiles.read_cgsmiles
+   cgsmiles.read_fragments
+   cgsmiles.resolve
+   cgsmiles.sample
+   cgsmiles.write_cgsmiles
+
+Module contents
+---------------
+
+.. automodule:: cgsmiles
+   :members:

docs/source/api/cgsmiles.sample.rst

@@ -0,0 +1,5 @@
+cgsmiles.sample module
+======================
+
+.. automodule:: cgsmiles.sample
+   :members:

docs/source/api/cgsmiles.write_cgsmiles.rst

@@ -0,0 +1,5 @@
+cgsmiles.write\_cgsmiles module
+===============================
+
+.. automodule:: cgsmiles.write_cgsmiles
+   :members:

docs/source/api/modules.rst

@@ -0,0 +1,7 @@
+cgsmiles
+========
+
+.. toctree::
+   :maxdepth: 4
+
+   cgsmiles