From fb6ca470898e38bd1eb0288464b726006c2d6347 Mon Sep 17 00:00:00 2001
From: Xavier Robin <xavalias-github@xavier.robin.name>
Date: Thu, 27 Jun 2024 17:21:28 +0200
Subject: [PATCH] doc: cleanup and make things more consistent.
The breadcrumbs now correctly indicate the module hierarchy and can be
used to determine imports. All the documentation for ost.* is now rooted
on the base `ost` module for more clarity.
---
modules/base/doc/base.rst | 15 +++++++++
modules/base/doc/settings.rst | 2 +-
modules/{ => base}/doc/table.rst | 0
modules/conop/doc/cleanup.rst | 2 +-
modules/db/doc/db.rst | 2 +-
modules/img/alg/doc/alg.rst | 2 +-
modules/img/base/doc/img.rst | 1 +
modules/index.rst | 32 +------------------
modules/mol/alg/doc/chain_mapping.rst | 2 +-
modules/mol/alg/doc/contact_score.rst | 4 +--
modules/mol/alg/doc/dockq.rst | 2 +-
modules/mol/alg/doc/helix_kinks.rst | 2 +-
modules/mol/alg/doc/lddt.rst | 8 +++--
modules/mol/alg/doc/ligand_scoring.rst | 2 +-
modules/mol/alg/doc/molalg.rst | 26 ++++++++-------
modules/mol/alg/doc/molck.rst | 7 +++--
modules/mol/alg/doc/qsscore.rst | 2 +-
modules/mol/alg/doc/scoring.rst | 2 +-
modules/mol/alg/doc/stereochemistry.rst | 2 +-
modules/mol/alg/doc/structure_analysis.rst | 2 +-
modules/mol/alg/doc/trajectory_analysis.rst | 2 +-
modules/mol/base/doc/mol.rst | 12 ++-----
modules/mol/mm/doc/antechamber.rst | 30 ++++++++++++++++++
modules/mol/mm/doc/forcefield.rst | 35 ++-------------------
modules/mol/mm/doc/molmm.rst | 3 +-
modules/seq/alg/doc/aaindex.rst | 2 +-
modules/seq/alg/doc/renumber.rst | 2 +-
modules/seq/alg/doc/seqalg.rst | 9 ++++--
modules/seq/base/doc/seq.rst | 6 ++++
29 files changed, 106 insertions(+), 112 deletions(-)
rename modules/{ => base}/doc/table.rst (100%)
create mode 100644 modules/mol/mm/doc/antechamber.rst
diff --git a/modules/base/doc/base.rst b/modules/base/doc/base.rst
index 72d9ed9dc..24bbf4448 100644
--- a/modules/base/doc/base.rst
+++ b/modules/base/doc/base.rst
@@ -2,7 +2,22 @@
================================================================================
.. toctree::
+ :maxdepth: 1
+ generic
logging
+ ../bindings/bindings
+ ../conop/conop
+ ../db/db
+ ../geom/geom
+ ../gfx/gfx
+ ../gui/gui
+ ../img/base/img
+ ../io/io
+ ../mol/base/mol
+ ../seq/base/seq
settings
+ table
testutils
+
+
diff --git a/modules/base/doc/settings.rst b/modules/base/doc/settings.rst
index 8ba0ffc37..ffd01d0e7 100644
--- a/modules/base/doc/settings.rst
+++ b/modules/base/doc/settings.rst
@@ -1,4 +1,4 @@
-:mod:`ost.settings` - Locate Files and Retrieve Preferences
+:mod:`~ost.settings` - Locate Files and Retrieve Preferences
================================================================================
.. automodule:: ost.settings
diff --git a/modules/doc/table.rst b/modules/base/doc/table.rst
similarity index 100%
rename from modules/doc/table.rst
rename to modules/base/doc/table.rst
diff --git a/modules/conop/doc/cleanup.rst b/modules/conop/doc/cleanup.rst
index a7a49bdf6..4f1881762 100644
--- a/modules/conop/doc/cleanup.rst
+++ b/modules/conop/doc/cleanup.rst
@@ -1,4 +1,4 @@
-:mod:`conop.cleanup <ost.conop.cleanup>` -- Sanitize structures
+:mod:`~ost.conop.cleanup>` -- Sanitize structures
================================================================================
.. module:: ost.conop.cleanup
diff --git a/modules/db/doc/db.rst b/modules/db/doc/db.rst
index a9f2cb59f..98a15ddc0 100644
--- a/modules/db/doc/db.rst
+++ b/modules/db/doc/db.rst
@@ -1,4 +1,4 @@
-Linear Database
+:mod:`~ost.db` - Linear Database
===============================================================================
.. currentmodule:: ost.db
diff --git a/modules/img/alg/doc/alg.rst b/modules/img/alg/doc/alg.rst
index 57584f489..1825f56c5 100644
--- a/modules/img/alg/doc/alg.rst
+++ b/modules/img/alg/doc/alg.rst
@@ -1,4 +1,4 @@
-:mod:`img.alg <ost.img.alg>` - Image Processing Algorithms
+:mod:`~ost.img.alg` - Image Processing Algorithms
================================================================================
.. module:: ost.img.alg
diff --git a/modules/img/base/doc/img.rst b/modules/img/base/doc/img.rst
index 9fe712166..0cd470a66 100644
--- a/modules/img/base/doc/img.rst
+++ b/modules/img/base/doc/img.rst
@@ -5,6 +5,7 @@
:hidden:
point-size-extent
+ ../alg/alg
.. module:: ost.img
:synopsis: Images and density maps
diff --git a/modules/index.rst b/modules/index.rst
index e307b9702..9a286f1c1 100644
--- a/modules/index.rst
+++ b/modules/index.rst
@@ -8,40 +8,10 @@ OpenStructure documentation
install
intro
users
- base/generic
base/base
- geom/geom
- mol/base/mol
- mol/alg/molalg
- mol/alg/chain_mapping
- mol/alg/contact_score
- mol/alg/dockq
- mol/alg/helix_kinks
- mol/alg/ligand_scoring
- mol/alg/qsscore
- mol/alg/scoring
- mol/alg/stereochemistry
- mol/alg/structure_analysis
- mol/alg/trajectory_analysis
- mol/mm/molmm
- conop/conop
- img/base/img
- img/alg/alg
- seq/base/seq
- seq/alg/seqalg
- seq/alg/renumber
- seq/alg/aaindex
- db/db
- bindings/bindings
- io/io
- gfx/gfx
- gui/gui
newmodule
external
contributing
- table
- mol/alg/lddt
- mol/alg/molck
actions
For Starters
@@ -108,7 +78,7 @@ Graphical User Interface
Varia
--------------------------------------------------------------------------------
-**Datasets**: :doc:`tabular data <table>`
+**Datasets**: :doc:`tabular data <base/table>`
**Supported File Formats**: :doc:`structure formats<io/structure_formats>` | :doc:`sequence formats <io/sequence_formats>` | :doc:`sequence profile formats <io/sequence_profile_formats>` | :doc:`image formats <io/image_formats>`
diff --git a/modules/mol/alg/doc/chain_mapping.rst b/modules/mol/alg/doc/chain_mapping.rst
index eeb69d34a..0933f2526 100644
--- a/modules/mol/alg/doc/chain_mapping.rst
+++ b/modules/mol/alg/doc/chain_mapping.rst
@@ -1,4 +1,4 @@
-:mod:`mol.alg.chain_mapping <ost.mol.alg.chain_mapping>` -- Chain Mapping
+:mod:`~ost.mol.alg.chain_mapping` -- Chain Mapping
--------------------------------------------------------------------------------
.. automodule:: ost.mol.alg.chain_mapping
diff --git a/modules/mol/alg/doc/contact_score.rst b/modules/mol/alg/doc/contact_score.rst
index 489ff85d7..ebc839d47 100644
--- a/modules/mol/alg/doc/contact_score.rst
+++ b/modules/mol/alg/doc/contact_score.rst
@@ -1,7 +1,7 @@
-:mod:`mol.alg.contact_score <ost.mol.alg.contact_score>` -- Contact based scores
+:mod:`~ost.mol.alg.contact_score` -- Contact-Based Scores
------------------------------------------------------------------------------------
.. automodule:: ost.mol.alg.contact_score
:members:
:member-order: bysource
- :synopsis: Contact based scores
+ :synopsis: Contact-based scores
diff --git a/modules/mol/alg/doc/dockq.rst b/modules/mol/alg/doc/dockq.rst
index 82b261fa7..4eabd307f 100644
--- a/modules/mol/alg/doc/dockq.rst
+++ b/modules/mol/alg/doc/dockq.rst
@@ -1,4 +1,4 @@
-:mod:`mol.alg.dockq <ost.mol.alg.dockq>` -- DockQ implementation
+:mod:`~ost.mol.alg.dockq` -- DockQ Implementation
--------------------------------------------------------------------------------
.. module:: ost.mol.alg.dockq
diff --git a/modules/mol/alg/doc/helix_kinks.rst b/modules/mol/alg/doc/helix_kinks.rst
index d81aa79f0..37fc78bdb 100644
--- a/modules/mol/alg/doc/helix_kinks.rst
+++ b/modules/mol/alg/doc/helix_kinks.rst
@@ -1,4 +1,4 @@
-:mod:`mol.alg.helix_kinks <ost.mol.alg.helix_kinks>` -- Algorithms to calculate Helix Kinks
+:mod:`~ost.mol.alg.helix_kinks` -- Algorithms to Calculate Helix Kinks
---------------------------------------------------------------------------------------------------------------
.. automodule:: ost.mol.alg.helix_kinks
diff --git a/modules/mol/alg/doc/lddt.rst b/modules/mol/alg/doc/lddt.rst
index 1d0587104..ae4e6d3d0 100644
--- a/modules/mol/alg/doc/lddt.rst
+++ b/modules/mol/alg/doc/lddt.rst
@@ -1,6 +1,8 @@
-====
-lDDT
-====
+:orphan:
+
+========================
+lDDT binary (deprecated)
+========================
.. warning::
diff --git a/modules/mol/alg/doc/ligand_scoring.rst b/modules/mol/alg/doc/ligand_scoring.rst
index 8f775777b..79fcb8dce 100644
--- a/modules/mol/alg/doc/ligand_scoring.rst
+++ b/modules/mol/alg/doc/ligand_scoring.rst
@@ -1,4 +1,4 @@
-:mod:`mol.alg.ligand_scoring <ost.mol.alg.ligand_scoring>` -- Ligand scoring functions
+:mod:`~ost.mol.alg.ligand_scoring` -- Ligand scoring functions
------------------------------------------------------------------------------------------
.. module:: ost.mol.alg.ligand_scoring
diff --git a/modules/mol/alg/doc/molalg.rst b/modules/mol/alg/doc/molalg.rst
index b3e773731..aab9fc5e2 100644
--- a/modules/mol/alg/doc/molalg.rst
+++ b/modules/mol/alg/doc/molalg.rst
@@ -1,4 +1,4 @@
-:mod:`mol.alg <ost.mol.alg>` -- Algorithms for Structures
+:mod:`~ost.mol.alg` -- Algorithms for Structures
================================================================================
.. module:: ost.mol.alg
@@ -7,16 +7,19 @@
Submodules
--------------------------------------------------------------------------------
-* :doc:`chain_mapping – Chain Mapping <chain_mapping>`
-* :doc:`contact_score – Contact based scores<contact_score>`
-* :doc:`dockq – DockQ implementation<dockq>`
-* :doc:`helix_kinks – Algorithms to calculate Helix Kinks<helix_kinks>`
-* :doc:`ligand_scoring – Ligand scoring functions<ligand_scoring>`
-* :doc:`qsscore – New QS score implementation<qsscore>`
-* :doc:`scoring – Specialized scoring functions<scoring>`
-* :doc:`stereochemistry – Stereochemistry Checks<stereochemistry>`
-* :doc:`structure_analysis – Functions to analyze structures<structure_analysis>`
-* :doc:`trajectory_analysis – DRMSD, pairwise distances and more<trajectory_analysis>`
+.. toctree::
+ :maxdepth: 1
+
+ chain_mapping
+ contact_score
+ dockq
+ helix_kinks
+ ligand_scoring
+ qsscore
+ scoring
+ stereochemistry
+ structure_analysis
+ trajectory_analysis
Local Distance Test scores (lDDT, DRMSD)
--------------------------------------------------------------------------------
@@ -1451,4 +1454,3 @@ from a :class:`ost.io.MMCifInfoBioUnit` or the derived
:param bu_info: Info object
:type bu_info: :class:`MMCifInfoBioUnit`/:class:`BUInfo`
:returns: A :class:`ost.mol.EntityHandle` of the requested biounit
-
diff --git a/modules/mol/alg/doc/molck.rst b/modules/mol/alg/doc/molck.rst
index 7c4d9ee63..c344308c7 100644
--- a/modules/mol/alg/doc/molck.rst
+++ b/modules/mol/alg/doc/molck.rst
@@ -1,9 +1,10 @@
+:orphan:
+
.. Note on large code blocks: keep max. width to 100 or it will look bad
on webpage!
-=========================
-Molecular Checker (Molck)
-=========================
+Molck - the Molecular Checker binary (deprecated)
+=================================================
--------------------------------------
Where can I find the Molck executable?
diff --git a/modules/mol/alg/doc/qsscore.rst b/modules/mol/alg/doc/qsscore.rst
index d2c2d9eeb..1422d625a 100644
--- a/modules/mol/alg/doc/qsscore.rst
+++ b/modules/mol/alg/doc/qsscore.rst
@@ -1,4 +1,4 @@
-:mod:`mol.alg.qsscore <ost.mol.alg.qsscore>` -- New QS score implementation
+:mod:`~ost.mol.alg.qsscore` -- New QS Score Implementation
--------------------------------------------------------------------------------
.. note::
diff --git a/modules/mol/alg/doc/scoring.rst b/modules/mol/alg/doc/scoring.rst
index 4b0f6a7a7..a9651f5fa 100644
--- a/modules/mol/alg/doc/scoring.rst
+++ b/modules/mol/alg/doc/scoring.rst
@@ -1,4 +1,4 @@
-:mod:`mol.alg.scoring <ost.mol.alg.scoring>` -- Specialized scoring functions
+:mod:`~ost.mol.alg.scoring` -- Specialized Scoring Functions
---------------------------------------------------------------------------------
.. module:: ost.mol.alg.scoring
diff --git a/modules/mol/alg/doc/stereochemistry.rst b/modules/mol/alg/doc/stereochemistry.rst
index 0ed0dd38f..78ebf8b02 100644
--- a/modules/mol/alg/doc/stereochemistry.rst
+++ b/modules/mol/alg/doc/stereochemistry.rst
@@ -1,4 +1,4 @@
-:mod:`mol.alg.stereochemistry <ost.mol.alg.stereochemistry>` -- Stereochemistry Checks
+:mod:`~ost.mol.alg.stereochemistry` -- Stereochemistry Checks
--------------------------------------------------------------------------------------
.. warning::
diff --git a/modules/mol/alg/doc/structure_analysis.rst b/modules/mol/alg/doc/structure_analysis.rst
index 681508ac8..79e679ac7 100644
--- a/modules/mol/alg/doc/structure_analysis.rst
+++ b/modules/mol/alg/doc/structure_analysis.rst
@@ -1,4 +1,4 @@
-:mod:`mol.alg.structure_analysis <ost.mol.alg.structure_analysis>` -- Functions to analyze structures
+:mod:`~ost.mol.alg.structure_analysis` -- Functions to Analyze Structures
---------------------------------------------------------------------------------------------------------------
.. automodule:: ost.mol.alg.structure_analysis
diff --git a/modules/mol/alg/doc/trajectory_analysis.rst b/modules/mol/alg/doc/trajectory_analysis.rst
index d83c0b259..b771f65f8 100644
--- a/modules/mol/alg/doc/trajectory_analysis.rst
+++ b/modules/mol/alg/doc/trajectory_analysis.rst
@@ -1,4 +1,4 @@
-:mod:`mol.alg.trajectory_analysis <ost.mol.alg.trajectory_analysis>` -- DRMSD, pairwise distances and more
+:mod:`~ost.mol.alg.trajectory_analysis` -- DRMSD, Pairwise Distances and More
---------------------------------------------------------------------------------------------------------------
.. automodule:: ost.mol.alg.trajectory_analysis
diff --git a/modules/mol/base/doc/mol.rst b/modules/mol/base/doc/mol.rst
index b6833b050..37f7a811f 100644
--- a/modules/mol/base/doc/mol.rst
+++ b/modules/mol/base/doc/mol.rst
@@ -8,6 +8,7 @@
The mol module implements data structures to work with molecular datasets. At its heart lie the :class:`EntityHandle` and :class:`EntityView` classes which represent molecular structures such as proteins, DNA, RNA and small molecules. There are also classes to deal with molecular surfaces.
.. toctree::
+ :maxdepth: 2
entity
editors
@@ -15,13 +16,4 @@ The mol module implements data structures to work with molecular datasets. At it
surface
traj
../alg/molalg
- ../alg/chain_mapping
- ../alg/contact_score
- ../alg/dockq
- ../alg/helix_kinks
- ../alg/ligand_scoring
- ../alg/qsscore
- ../alg/scoring
- ../alg/stereochemistry
- ../alg/structure_analysis
- ../alg/trajectory_analysis
\ No newline at end of file
+ ../mm/molmm
\ No newline at end of file
diff --git a/modules/mol/mm/doc/antechamber.rst b/modules/mol/mm/doc/antechamber.rst
new file mode 100644
index 000000000..ea975096a
--- /dev/null
+++ b/modules/mol/mm/doc/antechamber.rst
@@ -0,0 +1,30 @@
+:mod:`~ost.mol.mm.antechamber` -- Generating forcefields with Antechamber
+--------------------------------------------------------------------------------
+
+The antechamber submodule of mol.mm defines functions to use Antechamber (from
+AmberTools) to automatically generate force field parameters and load the
+results into :class:`~ost.mol.mm.Forcefield` objects.
+
+**Example usage**:
+
+.. code-block:: python
+
+ from ost.mol import mm
+
+ # create parameters for RVP using PDB's component dictionary
+ mm.antechamber.RunAntechamber('RVP', 'components.cif', base_out_dir='ligands')
+
+ # create force field
+ ff = mm.Forcefield()
+ ff = mm.antechamber.AddFromPath(ff, 'ligands/RVP')
+ # equivalent: ff = mm.antechamber.AddFromFiles(ff, 'ligands/RVP/frcmod',
+ # 'ligands/RVP/out.mpdb')
+ # since Antechamber cannot deal with ions, you can do it manually
+ ff = mm.antechamber.AddIon(ff, 'CL', 'CL', 35.45, -1.0, 0.4401, 0.4184)
+ # save it
+ ff.Save('ligands/ff.dat')
+
+**Functions**:
+
+.. automodule:: ost.mol.mm.antechamber
+ :members:
\ No newline at end of file
diff --git a/modules/mol/mm/doc/forcefield.rst b/modules/mol/mm/doc/forcefield.rst
index 5b88a42d1..b6a181687 100644
--- a/modules/mol/mm/doc/forcefield.rst
+++ b/modules/mol/mm/doc/forcefield.rst
@@ -139,33 +139,9 @@ Reading forcefields
Generating forcefields with Antechamber
--------------------------------------------------------------------------------
-The antechamber submodule of mol.mm defines functions to use Antechamber (from
-AmberTools) to automatically generate force field parameters and load the
-results into :class:`~ost.mol.mm.Forcefield` objects.
-
-**Example usage**:
-
-.. code-block:: python
-
- from ost.mol import mm
-
- # create parameters for RVP using PDB's component dictionary
- mm.antechamber.RunAntechamber('RVP', 'components.cif', base_out_dir='ligands')
-
- # create force field
- ff = mm.Forcefield()
- ff = mm.antechamber.AddFromPath(ff, 'ligands/RVP')
- # equivalent: ff = mm.antechamber.AddFromFiles(ff, 'ligands/RVP/frcmod',
- # 'ligands/RVP/out.mpdb')
- # since Antechamber cannot deal with ions, you can do it manually
- ff = mm.antechamber.AddIon(ff, 'CL', 'CL', 35.45, -1.0, 0.4401, 0.4184)
- # save it
- ff.Save('ligands/ff.dat')
-
-**Functions**:
-
-.. automodule:: ost.mol.mm.antechamber
- :members:
+The :doc:`antechamber <antechamber>` submodule of mol.mm defines functions to use
+Antechamber (from AmberTools) to automatically generate force field parameters
+and load the results into :class:`~ost.mol.mm.Forcefield` objects.
The Forcefield Class
--------------------------------------------------------------------------------
@@ -707,8 +683,3 @@ The Forcefield Class
:returns: :class:`BlockModifier` for this name, invalid if it can't
be found
-
-
-
-
-
diff --git a/modules/mol/mm/doc/molmm.rst b/modules/mol/mm/doc/molmm.rst
index e372ae76b..91e204529 100644
--- a/modules/mol/mm/doc/molmm.rst
+++ b/modules/mol/mm/doc/molmm.rst
@@ -1,4 +1,4 @@
-The mm Module
+:mod:`~ost.mol.mm` - The mm Module
================================================================================
.. module:: ost.mol.mm
@@ -79,6 +79,7 @@ Documentation
interaction
buildingblock
forcefield
+ antechamber
settings
topology
observers
diff --git a/modules/seq/alg/doc/aaindex.rst b/modules/seq/alg/doc/aaindex.rst
index cb8754814..940794d3f 100644
--- a/modules/seq/alg/doc/aaindex.rst
+++ b/modules/seq/alg/doc/aaindex.rst
@@ -1,4 +1,4 @@
-:mod:`seq.alg.aaindex <ost.seq.alg.aaindex>` -- AAIndex annotations
+:mod:`~ost.seq.alg.aaindex` -- AAIndex annotations
--------------------------------------------------------------------------------
.. module:: ost.seq.alg.aaindex
diff --git a/modules/seq/alg/doc/renumber.rst b/modules/seq/alg/doc/renumber.rst
index ff1618839..30688cd96 100644
--- a/modules/seq/alg/doc/renumber.rst
+++ b/modules/seq/alg/doc/renumber.rst
@@ -1,4 +1,4 @@
-:mod:`seq.alg.renumber <ost.seq.alg.renumber>` -- Renumber entities
+:mod:`~ost.seq.alg.renumber` -- Renumber entities
--------------------------------------------------------------------
.. module:: ost.seq.alg.renumber
diff --git a/modules/seq/alg/doc/seqalg.rst b/modules/seq/alg/doc/seqalg.rst
index 98e0568c6..117574c5f 100644
--- a/modules/seq/alg/doc/seqalg.rst
+++ b/modules/seq/alg/doc/seqalg.rst
@@ -1,4 +1,4 @@
-:mod:`seq.alg <ost.seq.alg>` -- Algorithms for Sequences
+:mod:`~ost.seq.alg` -- Algorithms for Sequences
================================================================================
.. module:: ost.seq.alg
@@ -7,8 +7,11 @@
Submodules
--------------------------------------------------------------------------------
-* :doc:`aaindex – AAIndex annotations <aaindex>`
-* :doc:`renumber – Renumber entities <renumber>`
+.. toctree::
+ :maxdepth: 1
+
+ aaindex
+ renumber
Algorithms for Alignments
--------------------------------------------------------------------------------
diff --git a/modules/seq/base/doc/seq.rst b/modules/seq/base/doc/seq.rst
index 012e31305..de8b0de19 100644
--- a/modules/seq/base/doc/seq.rst
+++ b/modules/seq/base/doc/seq.rst
@@ -863,3 +863,9 @@ probabilities between Match, Insertion or Deletion states or neff values
:returns: A nonsorted list of the names of all :class:`ProfileHandle`
objects in the database
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ ../alg/seqalg
\ No newline at end of file
--
GitLab