From ebfe155bd980ed30606a054502e8b87a69508301 Mon Sep 17 00:00:00 2001 From: Gerardo Tauriello <gerardo.tauriello@unibas.ch> Date: Mon, 11 Jan 2016 19:04:03 +0100 Subject: [PATCH] Cleanup documentation (user vs dev) and increased timeout for linkcheck --- CHANGELOG | 19 +++---------------- doc/buildsystem.rst | 6 +++--- doc/conf.py.in | 8 +++++++- doc/developers.rst | 18 +++++------------- doc/gettingstarted.rst | 8 ++++---- doc/index.rst | 7 +++++-- doc/users.rst | 17 ++++++++++++++++- 7 files changed, 43 insertions(+), 40 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index b50334fa..11de4c2e 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -5,20 +5,7 @@ Changelog ================================================================================ -Changes in Release 0.1 +Release 1.0 -------------------------------------------------------------------------------- - * initial setup of the CMake build system - * first idea of the documentation system - * meld included from SMNG as first module (to be modified/ renamed) - -Changes in Release 0.2 --------------------------------------------------------------------------------- - * added html documentation to repository - * meld renamed to rawmodel - -Changes in Release 0.3 (to be released) -------------------------------------------------------------------------------- - * merged argcheck into the helper module - * rawmodel renamed to modelling and including high-level modelling functions - -.. LocalWords: Changelog reStructuredText changelog txt + * initial release of ProMod3 + \ No newline at end of file diff --git a/doc/buildsystem.rst b/doc/buildsystem.rst index b90f9f10..1e584dc2 100644 --- a/doc/buildsystem.rst +++ b/doc/buildsystem.rst @@ -7,16 +7,16 @@ Building |project| Dependencies -------------------------------------------------------------------------------- |project| is build on top of |ost_l|_ (|ost_s|), requiring at least version -1.4. |ost_s| must be configured and compiled with ``ENABLE_MM=1`` to use |openmm|_. +1.5. |ost_s| must be configured and compiled with ``ENABLE_MM=1`` to use |openmm|_. To create the build system, |cmake|_ is required in version 2.8.7 or higher. |python|_ works well from version 2.7. For |ost_s| and the |C++| bit of |project|, |boost|_ is required in version 1.47.0 (the same as used for |ost_s|). Also |eigen3|_ and |lapack|_ are needed. To build -documentation, |sphinx|_ 1.2b1 is used. +documentation, |sphinx|_ 1.2b1 is required. The currently (Nov. 2015) preferred versions are: -* |ost_s|_ 1.4 +* |ost_s|_ 1.5 * |openmm|_ 6.1 * |cmake|_ 2.8.12 * |python|_ 2.7.5 diff --git a/doc/conf.py.in b/doc/conf.py.in index 737213b7..f9a16c14 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -56,7 +56,7 @@ master_doc = 'index' # General information about the project. project = u'ProMod3' -copyright = u'2015, Bienchen'# pylint: disable=redefined-builtin +copyright = u'2016, Bienchen'# pylint: disable=redefined-builtin # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -262,10 +262,12 @@ intersphinx_mapping = {'python': ('@PYTHON_DOC_URL@', None), 'openstructure': ('@OST_DOC_URL@', None)} # -- ProMod3 specific configuration -------------------------------------------- + extlinks = {'py_docs' : ('@PYTHON_DOC_URL@/%s', 'Python documentation'), 'ost_docs' : ('@OST_DOC_URL@/%s', 'OpenStructure documentation')} + # The _nameattr is a bit ugly: we want to have __name__ formatted as Python # attribute but Sphinx does not go with calling :attr: inside extlinks. To keep # the Python url prefix, we define sth here. Same holds for _mainattr. But this @@ -293,6 +295,10 @@ rst_epilog = """ .. |pep8| replace:: PEP 8 .. _pep8: https://www.python.org/dev/peps/pep-0008/ """ % project + +# increase default timeout (5s) for linkcheck +linkcheck_timeout = 15.0 + # in some versions of sphinx, doctest invokes doctest_path AFTER executing code doctest_global_setup = """ import sys diff --git a/doc/developers.rst b/doc/developers.rst index 2c4a920b..819a1e70 100644 --- a/doc/developers.rst +++ b/doc/developers.rst @@ -1,23 +1,15 @@ Documentation For Developers =============================================================================== -.. give an intro on what will be stored here -.. topics: how to create a new module, how to do doc (rst_epillog), - little bit on doctest & linkcheck, unit tests, directory structure + +This section is for developers that wish to extending the functionality of +|project|. It describes helper classes for development and how to contribute +new features. Contents: .. toctree:: :maxdepth: 2 - gettingstarted - core/setcompoundschemlib - core/index - modelling/index - loop/index - sidechain/index - actions/index_dev - buildsystem contributing + actions/index_dev cmake/index - -.. todolist:: diff --git a/doc/gettingstarted.rst b/doc/gettingstarted.rst index 696d3827..c2e78bfa 100644 --- a/doc/gettingstarted.rst +++ b/doc/gettingstarted.rst @@ -5,9 +5,8 @@ Get and Run |project| -------------------------------------------------------------------------------- First steps to get |project| up and running: -#. Get |ost_s|_. -#. Get |project| from the ``git`` repository (see :ref:`here <git-branches>`). -#. Compile |project| with ``cmake`` and ``make`` (see :ref:`here <building-promod>`). +#. Obtain all dependencies and compile |project| with ``cmake`` and ``make`` + (see :ref:`here <building-promod>`). #. Ensure that you have a ``stage/bin`` folder which includes a ``pm`` executable. For convenience, add the folder to your ``PATH`` env. variable. #. You can now execute |project| by running the following in your terminal: @@ -41,7 +40,8 @@ Modelling pipeline Commonly, your input is a template structure and an alignment of the template to the desired target sequence. The modelling steps then are: -- Build a raw model from the template (see :func:`~promod3.modelling.BuildRawModel` function) +- Build a raw model from a template by copying the part of the template which + is conserved - Perform loop modelling to close all gaps (see :mod:`~promod3.loop` module) - Reconstruct sidechains (see :mod:`~promod3.sidechain` module) - Minimize energy of final model using molecular mechanics diff --git a/doc/index.rst b/doc/index.rst index 102c6f13..0699c605 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,9 +13,12 @@ Contents: Users <users> Developers <developers> - changelog -.. todolist:: +.. toctree:: + :maxdepth: 1 + + changelog + Indices And Tables ================== diff --git a/doc/users.rst b/doc/users.rst index cf364d75..d1d77fcf 100644 --- a/doc/users.rst +++ b/doc/users.rst @@ -1,3 +1,18 @@ Documentation For Users ======================= -.. intro, primer on concept of actions, holistic ProMod and hint towards modules + +This section is for users of |project|. It describes how to compile and run +scripts using the functionality of this library. + +Contents: + +.. toctree:: + :maxdepth: 2 + + gettingstarted + buildsystem + modelling/index + loop/index + sidechain/index + core/index + core/setcompoundschemlib -- GitLab