From 48b41edb87393399997e58480fb6ece8184742e3 Mon Sep 17 00:00:00 2001 From: Patrick Kunzmann Date: Mon, 29 Apr 2024 12:40:55 +0200 Subject: [PATCH] Rework the contributor guide --- doc/contribute.rst | 430 ----------------------------- doc/contribution/deployment.rst | 79 ++++++ doc/contribution/development.rst | 187 +++++++++++++ doc/contribution/documentation.rst | 179 ++++++++++++ doc/contribution/index.rst | 66 +++++ doc/contribution/testing.rst | 65 +++++ doc/index.rst | 2 +- doc/scraper.py | 2 +- environment.yml | 2 +- 9 files changed, 579 insertions(+), 433 deletions(-) delete mode 100644 doc/contribute.rst create mode 100644 doc/contribution/deployment.rst create mode 100644 doc/contribution/development.rst create mode 100644 doc/contribution/documentation.rst create mode 100644 doc/contribution/index.rst create mode 100644 doc/contribution/testing.rst diff --git a/doc/contribute.rst b/doc/contribute.rst deleted file mode 100644 index 7e7c8cfed..000000000 --- a/doc/contribute.rst +++ /dev/null @@ -1,430 +0,0 @@ -.. This source code is part of the Biotite package and is distributed - under the 3-Clause BSD License. Please see 'LICENSE.rst' for further - information. - -Contributing -============ - -As the aim of *Biotite* is to create a comprehensive library, we welcome -developers who would like to extend the package with new functionalities or -improve existing code. - -The complete development workflow is hosted on -`GitHub `_. -This is also the place where you would post feature propositions, -questions, bug reports, etc. - -If you are interested in improving *Biotite*, you feel free join our chat on -`Discord `_. -We are happy to answer questions, discuss ideas and provide mentoring for -newcomers. -Alternatively, you can also contact ``_. -A good place to find projects to start with are the -`Open Issues `_ and -the `Project Boards `_. - -The following page explains the development guidelines in order to keep -*Biotite*'s source code consistent. - - -Writing code ------------- - -Scope -^^^^^ -The scope of *Biotite* are methods that make up the backbone of -computational molecular biology. Thus, new functionalities added to -*Biotite* should be relatively general and well established. - -Code of which the purpose is too special could be published as -:ref:`extension package `. - -Consistency -^^^^^^^^^^^ -New functionalities should work with existing types, if applicable. -Specifically, this includes for example :class:`AtomArray`, -:class:`AtomArrayStack`, :class:`Sequence`, :class:`Annotation` -and of course :class:`ndarray`. - -Python version and interpreter -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -*Biotite* is made for usage with Python 3.6 and upwards. -Therefore, no compatibility hacks for Python 2.x are necessary. -Furthermore, this package is currently made for use with CPython. -Support for PyPy might be added someday. - -Code style -^^^^^^^^^^ -*Biotite* is in compliance with PEP 8. The maximum line length is 79 for -code lines and 72 for docstring and comment lines. -An exception is made for docstring lines, if it is not possible to use a -maximum of 72 characters (e.g. tables), and for doctest style lines, where the -actual code may take up to 79 characters. - -Dependencies -^^^^^^^^^^^^ -*Biotite* currently depends on `numpy`, `requests`, `msgpack`. -The usage of these packages is not only allowed but even encouraged. -Further packages might be added to the dependencies in the future, so if you -need a specific package, you might open an issue on GitHub. -But keep in mind, that a simple installation process is a central aim of -*Biotite*, so the new dependency should neither be hard to install on any -system nor be poorly supported. - -Another approach is adding your special dependency to the list of extra -requirements in ``install.rst``. -In this case, put the import statement for the dependency directly into the -function or class, rather than module level, to ensure that the package is not -required for any other functionality or for building the API documentation. - -If your added code has a dependency that is too special, consider publishing -the code as :ref:`extension package `. - -Code efficiency -^^^^^^^^^^^^^^^ -Although convenient usage is a primary aim of *Biotite*, code efficiency -plays also an important role. -Therefore time consuming tasks should be C-accelerated, if possible. -The most convenient way to achieve this, is using *NumPy*. -In cases the problem is not vectorizable, writing modules in *Cython* are the -preferred way to go. -Writing pure C-extensions is discouraged due to the bad readability. - -Docstrings -^^^^^^^^^^ -*Biotite* uses -`numpydoc `_ -formatted docstrings for its documentation. -The docstrings can be interpreted by *Sphinx* via the *numpydoc* extension. -All publicly accessible attributes must be fully documented. -This includes functions, classes, methods, instance and class variables and the -``__init__`` modules. -The ``__init__`` module documentation summarizes the content of the entire -subpackage, since the single modules are not visible to the user. -Consequently, all other modules do not need to be fully documented on the -module level, one or two short sentences are sufficient. -In the class docstring, the class itself is described and the constructor is -documented. -The publicly accessible instance variables are documented under the -`Attributes` headline, while class variables are documented in their separate -docstrings. -Methods do not need to be summarized in the class docstring. - -Module imports -^^^^^^^^^^^^^^ - -In *Biotite*, the user imports packages in contrast to single modules -(similar to *NumPy*). -In order for that to work, the ``__init__.py`` file of each *Biotite* -subpackage needs to import all of its modules, whose content is publicly -accessible, in a relative manner. - -.. code-block:: python - - from .module1 import * - from .module2 import * - -Import statements should be the only statements in a ``__init__.py`` file. - -In case a module needs functionality from another subpackage of *Biotite*, -use a relative import. -This import should target the module directly and not the package. -So import statements like the following are totally OK: - -.. code-block:: python - - from ...package.subpackage.module import foo - -In order to prevent namespace pollution, all modules must define the `__all__` -variable with all publicly accessible attributes of the module. - -When using *Biotite* internal imports, always use relative imports. Otherwise -:ref:`in-development testing ` is not possible. - -.. Type annotations - ^^^^^^^^^^^^^^^^ - - *Biotite* obligatorily uses type annotations (:PEP:`484`) for its public API. - This enables static type checkers (e.g. *mypy*) to detect programming errors - at compile time. - Instead of using inline type annotations, the type hints are outsourced - into ``*.pyi`` stub files, that exist alongside ``*.py`` files with the same - module name. - Although, *NumPy* does not support type hints yet, the `ndarray` type is still - used in type annotations - - - -Writing the documentation -------------------------- - -Any documentation apart from the API reference is placed in the ``doc`` -folder. -*Biotite* uses *Sphinx* for building its documentation and therefore the -documentation is based on *reStructuredText* files. -The line length of these ``*.rst`` files is also limited to -79 characters, with the exceptions already mentioned above. - -Contributing examples -^^^^^^^^^^^^^^^^^^^^^ - -Do you have an application of *Biotite* and you want to share it with the -world? -Then the example gallery is the way to go. -For gallery generation the package *sphinx-gallery* is used. -Please refer to its -`documentation `_ -for further information on script formatting. -The example scripts are placed in ``doc/examples/scripts``. - -Static images and molecular visualizations -"""""""""""""""""""""""""""""""""""""""""" - -In addition to *Matplotlib* plots, the *Biotite* example gallery can also -show molecular visualizations, via the *PyMOL* software, and static images. - -Static images can be included by adding the following comment in the -corresponding code block: - -.. code-block:: python - - # sphinx_gallery_static_image = .png - -The image file must be stored in the same directory as the example script. - -| - -To visualize images using *PyMOL*, the -`Ammolite `_ package is required. -Please make sure to use open-source *PyMOL* to avoid licensing issues. - -Let's assume you have an example script `.py`. -The visualization is initiated by adding the comment line - -.. code-block:: python - - # sphinx_gallery_ammolite_script = .py - -in the code block where you want show the visualization. -Then the visualization script ``.py`` is executed, which -can use the global variables from the example script and the special -``__image_destination__`` variable. -``__image_destination__`` is a string representing the path to the output image -file. -The PyMOL visualization can be saved to this file with e.g. - -```python -ammolite.cmd.png(__image_destination__) -``` - -The rendered image is saved in the directory of the example script as -``.png`` and is added to version control. -The visualization script is only executed, if the rendered image does not -exist, yet. -The traceback of errors in the visualization script are printed, if -``sphinx-build`` is run in verbose (``-v``) mode. -An example of this can be seen in the -``doc/examples/structure/contact_sites.py`` example. - - -Updating the tutorial -^^^^^^^^^^^^^^^^^^^^^ - -When adding new content for broad audience, it is appreciated to update the -tutorial pages (``doc/tutorial/src``) as well. -The tutorial uses functionality from ``sphinx-gallery`` to generate -the tutorial from example scripts. -This has the advantage that the output of code snippets is not static but -dynamically generated based on the current state of the *Biotite* source -code. -Consequently, the same script formatting as for the example gallery is -required. -Figures that cannot be dynamically generated are put into -``doc/static/assets/figures``. - -Structuring the API reference -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Each *Biotite* subpackage has a dedicated reference page, describing -its classes and functions. -The categories and classes/functions that are assigned to it can be set -in ``apidoc.json``. -Classes/functions that are not assigned to any category are placed in -the 'Miscellaneous' category or, if no class/function is assigned, -in the 'Content' category. - -Citing articles -^^^^^^^^^^^^^^^ - -*Biotite* uses -`sphinxcontrib-bibtex `_ for -creating references in docstrings, examples, etc. -The references are stored in ``doc/references.bib`` with citation keys -in ``[Author][year]`` format. -References are cited with the ``:footcite:`` role and the bibliography -is rendered where the ``.. footbibliography::`` directive is placed. - - - -Code testing ------------- - -.. _tests: - -In-development tests -^^^^^^^^^^^^^^^^^^^^ - -For simple tests of your code, you are free to use a ``test.py`` file in the -top-level directory since this file is ignored in the ``.gitignore`` file. -Remember you have to have to use relative imports, as long as you do not want -to build and install the package after each small code change. -Therefore, the *import* statements in ``test.py`` will look similar to this: - -.. code-block:: python - - import src.biotite - import src.biotite.sequence as seq - import src.biotite.structure as struc - ... - -Alternatively, you can install *Biotite* in development mode via -`pip install -e .`. - -If you are writing or using an extension module in Cython, consider using -`pyximport` at the beginning of ``test.py``. - -.. code-block:: python - - import pyximport - pyximport.install() - -Unit tests -^^^^^^^^^^ - -In order to check if your new awesome code breaks anything in *Biotite*, -you should run unit tests before you open a pull request. -To achieve that, install the package and run ``pytest`` in the top-level -directory. - -.. code-block:: console - - $ pip install . - $ pytest - -Adding your own unit tests for your new module (if possible), is appreciated. -The unit tests are found in the ``tests`` folder (big surprise!). -If there is already an appropriate module for you, then just add your own test -function to it. -If not, create your own module and put your test function into it. - - - -Code deployment ---------------- - -The binary distribution and the source distribution are created with -the following commands, respectively: - -.. code-block:: console - - $ python setup.py bdist_wheel - $ python setup.py sdist - -Building the documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The Sphinx documentation is created using - -.. code-block:: console - - $ pip install -e . - $ sphinx-build doc build/doc - -in the top-level directory. -The building process can take a while, since the code from the tutorial -and the example gallery is executed. -In order to omit building the tutorial and gallery, type - -.. code-block:: console - - $ sphinx-build -D plot_gallery=0 doc build/doc - -instead. - -Building the tutorial and the gallery may raise a ``RequestError`` due to -a hight number of requests to the NCBI Entrez database. -This can be fixed by exporting the ``NCBI_API_KEY`` environment variable, -containing an -`NCBI API key `_. - - -Required packages ------------------ - -The following packages are required for the complete build process -including the creation of the entire documentation: - - - *numpy* - - *scipy* - - *networkx* - - *matplotlib* - - *requests* - - *msgpack* - - *mdtraj* - - *cython* - - *pytest* - - *sphinx* - - *numpydoc* - - *sphinx-gallery* - - *sphinxcontrib-bibtex* - -Furthermore, the following software must be installed: - - - *MUSCLE* - - *MAFFT* - - *Clustal Omega* - - *DSSP* - - *NCBI sra-tools* - - *Autodock Vina* - -If you use the *Conda* package manager, there is a shortcut: -You can download a *Conda* environment from -`here `_, -that contains all of these requirements. -How to create and activate the environment from the ``environment.yml`` file, -is explained in the -`conda documentation `_. - - -.. _extensions: - -Extension packages ------------------- - -*Biotite* extension packages are Python packages that provide further -functionality for *Biotite* objects (:class:`AtomArray`, :class:`Sequence`, -etc.) -or offer objects that build up on these ones. - -There can be good reasons why one could choose to publish code as extension -package instead of contributing it directly to the *Biotite* project: - - - Independent development - - An incompatible license - - The code's use cases are too specialized - - Unsuitable dependencies - - Acceleration by C/C++ code (in contrast to Cython code) - -If your code fulfills the following conditions - - - extends *Biotite* functionality - - is documented - - is well tested - -you can contact the *Biotite* maintainer or open an issue -to ask for official acceptance as extension package. - -The current extension packages are displayed on the -:doc:`extensions section ` -in the -documentation. diff --git a/doc/contribution/deployment.rst b/doc/contribution/deployment.rst new file mode 100644 index 000000000..6f1e6ab28 --- /dev/null +++ b/doc/contribution/deployment.rst @@ -0,0 +1,79 @@ +Deployment of a new release +=========================== +This section describes how create and deploy a release build of the *Biotite* +package and documentation. +Therefore, this section primarily addresses the maintainers of the project. + +CCD update +---------- +:mod:`biotite.structure.info` bundles selected information from the +`Chemical Component Dictionary `_ (CCD). +From time to time, this dataset needs an update to include new components +added to the CCD. +This is achieved by running ``setup_ccd.py``. + +To keep the size of the repository small, the original commit from the initial +script run should be rewritten, if the formats of the affected files are +compatible with the original ones. + +Version bump +------------ +A version bump requires changes in multiple locations: + +- ``src/biotite/__init__.py``: The main source of the version number. +- ``doc/static/switcher.json``: The current version needs to be added and set + as the preferred one. This allows the documentation website to switch between + different versions of the documentation. + +The version bump is conducted by running the ``bump_version.yml`` CI job. +It can be triggered via the GitHub Action ``Bump version``. +This action creates a new pull request with the required changes. + +Creating a new release +---------------------- +When a new *GitHub* release is created, the CI jobs building the distributions +and documentation in ``test_and_deploy.yml`` are triggered. +After the successful completion of these jobs, the artifacts are added to the +release. +The distributions for different platforms and Python versions are automatically +uploaded to *PyPI*. + +Conda release +------------- +Some time after the release on GitHub, the ``conda-forge`` bot will also create +an automatic pull request for the new release of the +`Conda package `_. +If no dependencies changed, this pull request can usually be merged without +further effort. + +Documentation website +--------------------- +The final step of the deployment is putting the directory containing the built +documentation onto the server hosting the website. + +The document root of the website should look like this: + +.. code-block:: + + ├─ .htaccess + ├─ latest -> x.y.z/ + ├─ x.y.z/ + │ ├─ index.html + │ ├─ ... + ├─ a.b.c/ + ├─ index.html + ├─ ... + +``x.y.z/`` and ``a.b.c/`` represent the documentation directories for two +different *Biotite* release versions. + +``.htaccess`` should have the following content: + +.. code-block:: apache + + RewriteBase / + RewriteEngine On + # Redirect if page name does not start with 'latest' or version identifier + RewriteRule ^(?!latest|\d+\.\d+\.\d+|robots.txt)(.*) latest/$1 [R=301,L] + + ErrorDocument 404 /latest/404.html \ No newline at end of file diff --git a/doc/contribution/development.rst b/doc/contribution/development.rst new file mode 100644 index 000000000..3d1360740 --- /dev/null +++ b/doc/contribution/development.rst @@ -0,0 +1,187 @@ +Writing source code +=================== + +Scope +----- +The scope of *Biotite* are methods that make up the backbone of +computational molecular biology. Thus, new functionalities added to +*Biotite* should be relatively general and well established. + +Code of which the purpose is too special could be published as +:ref:`extension package ` instead. + +Consistency +----------- +New functionalities should act on the existing central classes, if applicable +to keep the code as uniform as possible. +Specifically, these include + +- :class:`biotite.structure.AtomArray`, +- :class:`biotite.structure.AtomArrayStack`, +- :class:`biotite.structure.BondList`, +- :class:`biotite.sequence.Sequence` and its subclasses, +- :class:`biotite.sequence.Alphabet`, +- :class:`biotite.sequence.Annotation`, + including :class:`biotite.sequence.Feature` + and :class:`biotite.sequence.Location`, +- :class:`biotite.sequence.AnnotatedSequence`, +- :class:`biotite.sequence.Profile`, +- :class:`biotite.sequence.align.Alignment`, +- :class:`biotite.application.Application` and its subclasses, +- and in general :class:`numpy.ndarray`. + +If you think that the currently available classes miss a central *object* +in bioinformatics, you might consider opening an issue on *GitHub* or reach +out to the maintainers. + +Small *helper classes* for a functionality (for example an :class:`Enum` for a +function parameter) is also permitted, as long as it does not introduce a +redundancy with the classes mentioned above. + +Python version and interpreter +------------------------------ +The package supports the three most recent versions of Python. +In consequence, language features that were introduced after the oldest +supported Python version are not allowed. + +This time span balances the support for older Python versions as well as +the ability to use more recent features of the programming language. +Furthermore, this package is currently made for usage with CPython. +Official support for PyPy might be added someday. + +Code style +---------- +*Biotite* is in compliance with PEP 8. +The maximum line length is 79 for code lines and 72 for docstring and +comment lines. +An exception is made for docstring lines, if it is not possible to use a +maximum of 72 characters (e.g. tables), and for +`doctest `_ lines, +where the actual code may take up to 79 characters. + +Dependencies +------------ +*Biotite* aims to rely only on a few dependencies to keep the installation +small. +However optional dependencies for a specific dependency are also allowed if +necessary. +In this case add your special dependency to the list of extra +requirements in ``install.rst``. +The import statement for the dependency should be located directly inside the +function or class, rather than module level, to ensure that the package is not +required for any other functionality or for building the API documentation. + +An example for this approach is the support for trajectory files in +:mod:`biotite.structure.io`, that require `MDTraj `_. +The usage of these packages is not only allowed but even encouraged. + +Code efficiency +--------------- +The central aims of *Biotite* are that it is both, convenient and fast. +Therefore, the code should be vectorized as much as possible using *NumPy*. +In cases the problem cannot be reasonably or conveniently solved this way, +writing modules in `Cython `_ is the +preferred way to go. +Writing extensions directly in C/C++ is discouraged due to the bad readability. +Writing extensions in other programming languages +(e.g. in *Rust* via `PyO3 `_) is currently not permitted to +keep the build process simple. + +Docstrings +---------- +*Biotite* uses +`numpydoc `_ +formatted docstrings for its documentation. +These docstrings can be interpreted by *Sphinx* via the ``numpydoc`` extension. +All publicly accessible attributes must be fully documented. +This includes functions, classes, methods, instance and class variables and the +``__init__`` modules: + +The ``__init__`` module documentation summarizes the content of the entire +subpackage, since the single modules are not visible to the user. +In the class docstring, the class itself is described and the constructor is +documented. +The publicly accessible instance variables are documented under the +`Attributes` headline, while class variables are documented in their separate +docstrings. +Methods do not need to be summarized in the class docstring. + +Module imports +-------------- +In *Biotite*, the user imports packages in contrast to single modules +(similar to *NumPy*). +In order for that to work, the ``__init__.py`` file of each *Biotite* +subpackage needs to import all of its modules, whose content is publicly +accessible, in a relative manner. + +.. code-block:: python + + from .module1 import * + from .module2 import * + +Import statements should be the only statements in a ``__init__.py`` file. + +In case a module needs functionality from another subpackage of *Biotite*, +use a relative import. +This import should target the module directly and not the package to avoid +circular imports and thus an ``ImportError``. +So import statements like the following are totally OK: + +.. code-block:: python + + from ...package.subpackage.module import foo + +In order to prevent namespace pollution, all modules must define the `__all__` +variable with all publicly accessible attributes of the module. + +Versioning +---------- +Biotite adopts `Semantic Versioning `_ for its releases. +This means that the version number is composed of three parts: + +- Major version: Incremented when incompatible API changes are made. +- Minor version: Incremented when a new functionality is added in a backwards + compatible manner. +- Patch version: Incremented when backwards compatible bug fixes are made. + +Note, that such backwards incompatible changes in minor/patch versions are only +disallowed regarding the *public API*. +This means that names and types of parameters and the type of the return value +must not be changed in any function/class documented in the API reference. +However, behavioral changes (especially small ones) are allowed. + +Although minor versions may not remove existing functionalities, they can +deprecate them by + +- marking them as deprecated via a notice in the docstring and +- raising a `DeprecationWarning` when a deprecated functionality is used. + +This gives the user a heads-up that the functionality will be removed soon. +In the next major version, deprecated functionalities can be removed entirely. + +.. _extension_packages: + +Extension packages +------------------ +*Biotite* extension packages are Python packages that provide further +functionality for *Biotite* objects (:class:`AtomArray`, :class:`Sequence`, +etc.) +or offer objects that build up on these ones. + +There can be good reasons why one could choose to publish code as extension +package instead of contributing it directly to the *Biotite* project: + + - Independent development + - An incompatible license + - The code's use cases are too specialized + - Unsuitable dependencies + - Extensions written in a non-permitted programming language + +If your code fulfills the following conditions + + - extends *Biotite* functionality + - is documented + - is well tested + +you can open an issue to ask for addition of the package to the +:doc:`extension package page <../extensions>`. diff --git a/doc/contribution/documentation.rst b/doc/contribution/documentation.rst new file mode 100644 index 000000000..7d402cfdf --- /dev/null +++ b/doc/contribution/documentation.rst @@ -0,0 +1,179 @@ +Writing the documentation +========================= + +Having a good documentation on a package is arguably as important as the +code itself. +Hence, *Biotite* provides in addition to the API reference documented in +docstrings, a comprehensive documentation residing in the ``doc/`` directory +containing tutorials, examples and more. + +Documentation generation +------------------------ +*Biotite* uses the widely used `Sphinx `_ package +for generating its documentation. +Therefore, the documentation is based on *reStructuredText* files. +The line length of these ``*.rst`` files is also limited to 79 characters +where reasonable. + +To build the documentation, run from the root directory of the repository: + +.. code-block:: console + + $ sphinx-build doc build/doc + +Documentation structure +----------------------- +*Biotite* employs the +`Divio documentation system `_. +In short, the documentation is splitted into four different parts that +addresses different purposes and audiences: + +.. list-table:: Documentation sections + :widths: 10 20 20 + :header-rows: 1 + + * - Part + - Summary + - Section in *Biotite* + * - `Tutorials `_ + - Learning of basic concepts via simple examples + - Tutorial + * - `How-to guides `_ + - Step-by-step instructions for specific real-world tasks + - Example gallery + * - `Explanation `_ + - Detailed explanation of concepts + - Literature citations, contributor guide + * - `Reference `_ + - Technical description in a consistent format + - API reference + +When adding new content, please consider which part of the documentation +it fits best and adhere to the purpose of that part. +You might also consider to split the content into multiple parts +(e.g. into an example for the gallery and a tutorial), if you think your +content fulfills a mixture of different purposes. + +.. _example_gallery: + +Example gallery +--------------- +For gallery generation the package *sphinx-gallery* is used. +Please refer to its +`documentation `_ +for further information on script formatting. +The example scripts are placed in ``doc/examples/scripts`` in the subdirectory +that fits best topic of the example. +Choose a title for the example that focuses on the employed method rather than +the biological context. +For example, +'*Homology search and multiple sequence alignment of protein sequences*' +would be a better name than +'*Similarities of lysozyme variants**. + +Building the example gallery for the first time may take a while, as all +scripts are executed. +To build the documentation without the gallery, run + +.. code-block:: console + + $ sphinx-build -D plot_gallery=0 doc build/doc + +You may also ask the *Biotite* maintainers to run the example script and check +the generated page, if building the gallery on your device is not possible. + +Static images and molecular visualizations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In addition to *Matplotlib* plots, the *Biotite* example gallery can also +show molecular visualizations, via the *PyMOL* software, and static images. + +Static images can be included by adding the following comment in the +corresponding code block: + +.. code-block:: python + + # sphinx_gallery_static_image = .png + +The image file must be stored in the same directory as the example script. + +| + +To visualize images using *PyMOL*, the +`Ammolite `_ package is required. +Please make sure to use open-source *PyMOL* to avoid licensing issues. + +Let's assume you have an example script `.py`. +The visualization is initiated by adding the comment line + +.. code-block:: python + + # sphinx_gallery_ammolite_script = .py + +in the code block where you want show the visualization. +Then the visualization script ``.py`` is executed, which +can use the global variables from the example script and the special +``__image_destination__`` variable. +``__image_destination__`` is a string representing the path to the output image +file. +The PyMOL visualization can be saved to this file with e.g. + +.. code-block:: python + + ammolite.cmd.png(__image_destination__) + +The rendered image is saved in the directory of the example script as +``.png`` and is added to version control. +The visualization script is only executed, if the rendered image does not +exist, yet. +The traceback of errors in the visualization script are printed, if +``sphinx-build`` is run in verbose (``-v``) mode. +An example of this can be seen in the +``doc/examples/structure/contact_sites.py`` example. + +Tutorial +-------- +When adding new content for a broad audience, it is appreciated to update the +tutorial pages (``doc/tutorial/``) as well. +The tutorial uses `jupyter-sphinx `_ to +run the code snippets and show the results. +This has the advantage that the output of code snippets is not static but +dynamically generated based on the current state of the *Biotite* source +code. + +Make sure to add + +.. code-block:: rst + + .. include:: /tutorial/preamble.rst + +at the beginning of the tutorial page. + +API reference +------------- +Each *Biotite* subpackage has a dedicated reference page, describing +its classes and functions. +The categories and classes/functions that are assigned to it can be set +in ``doc/apidoc.json``. +Classes/functions that are not assigned to any category are placed in +the 'Miscellaneous' category or, if no class/function is assigned, +in the 'Content' category. + +Citing articles +--------------- +*Biotite* uses +`sphinxcontrib-bibtex `_ for +creating references in docstrings, examples, etc. +The references are stored in ``doc/references.bib`` with citation keys +in ``[Author][year]`` format. +References are cited with the ``:footcite:`` role and the bibliography +is rendered where the ``.. footbibliography::`` directive is placed. + +Setting NCBI API key +-------------------- +The example gallery as well as the tutorial use :mod:`biotite.database.entrez` +to fetch sequence data. +Hence, these scripts may raise a ``RequestError`` due to +a hight number of requests to the NCBI Entrez database. +This can be fixed by exporting the ``NCBI_API_KEY`` environment variable, +containing an +`NCBI API key `_. \ No newline at end of file diff --git a/doc/contribution/index.rst b/doc/contribution/index.rst new file mode 100644 index 000000000..8ce176550 --- /dev/null +++ b/doc/contribution/index.rst @@ -0,0 +1,66 @@ +.. This source code is part of the Biotite package and is distributed + under the 3-Clause BSD License. Please see 'LICENSE.rst' for further + information. + +Contributor guide +================= + +As the aim of *Biotite* is to create a comprehensive library, we welcome +developers who would like to extend the package with new functionalities or +improve existing code. +Contributing new examples to the gallery or improving the documentation +in general is also highly appreciated. + +The complete development workflow is hosted on +`GitHub `_. +This is also the place where you would post feature propositions, +questions, bug reports, etc. + +If you are interested in improving *Biotite*, you feel free join our chat on +`Discord `_. +We are happy to answer questions, discuss ideas and provide mentoring for +newcomers. +Alternatively, you can also contact ``_. +A good place to find projects to start with are the +`Open Issues `_ and +the `Project Boards `_. + +The following pages should explain development guidelines in +order to keep *Biotite*'s source code consistent. +Finally, the :doc:`deployment` describes the process of releasing a new +version of *Biotite*. + +Requirements +------------ + +Development of *Biotite* requires a few packages in addition to the ones +specified in +`pyproject.toml `_. +The full list is provided in +`environment.yml `_. +If you use the `Conda `_ package manager, you can simply +create a environment with all required dependencies by running + +.. code-block:: console + + $ conda env create -f environment.yml + $ conda activate biotite-dev + +Contributing examples +--------------------- + +Do you have an application of *Biotite* and you want to share it with the +world? +Then the example gallery is the way to go. +Head directly to the :ref:`gallery section ` to learn how to +contribute. + + +.. toctree:: + :maxdepth: 1 + :hidden: + + development + testing + documentation + deployment diff --git a/doc/contribution/testing.rst b/doc/contribution/testing.rst new file mode 100644 index 000000000..dc4b6b5f7 --- /dev/null +++ b/doc/contribution/testing.rst @@ -0,0 +1,65 @@ +Testing the package +=================== + +In-development tests +-------------------- +While developing a new feature or fixing a bug, it is handy to run a test +script against the code you are working on. +To ensure that the imported package ``biotite`` points to the code you are +working on, you may want to install the local repository clone in *editable* +mode: + +.. code-block:: console + + $ pip install -e . + +If you are writing or using an extension module in *Cython*, consider using +`pyximport `_ +at the beginning of the script you use for testing. + +.. code-block:: python + + import numpy as np + import pyximport + pyximport.install( + build_in_temp=False, + setup_args={"include_dirs":np.get_include()}, + language_level=3 + ) + +To enforce the recompilation of the changed *Cython* module, delete the +respective compiled module (``.dll`` or ``.so``) from the ``src/`` directory, +if already existing. + +Unit tests +---------- +The backbone of testing *Biotite* are the unit tests in the ``tests`` +directory. +`Pytest `_ is used as the testing framework. +To run the tests, install the local repository clone (in editable mode) and +run the tests: + +.. code-block:: console + + $ pip install -e . + $ pytest + +Doctests +-------- +For simple tests checking that some code simply does not raise an exception +and produces some predefined output, +`doctests `_ are suitable. +They are part of the docstrings of the corresponding functions and classes. +The doctests fulfill two purposes: +They are automatically executed by ``pytest`` via the +``tests/test_doctests.py`` module and give users reading the API reference +easily understandable examples how a function/class works. + +Testing visualizations +---------------------- +Testing visualization functions (e.g. in :mod:`biotite.sequence.graphics`) is +difficult, because the output can hardly be checked against some reference +value. +To still have at least some confirmation that these functions produce the +expected output, it is mandatory to have at least one example using that +function in the :ref:`gallery `. \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index e6cbf04f9..5ae91b4bd 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -208,7 +208,7 @@ Biotite documentation Interested in contributing to the project? - .. button-ref:: contribute + .. button-ref:: contribution/index :color: primary :outline: :shadow: diff --git a/doc/scraper.py b/doc/scraper.py index 5b7daf141..6df35dbae 100644 --- a/doc/scraper.py +++ b/doc/scraper.py @@ -46,7 +46,7 @@ def static_image_scraper(block, block_vars, gallery_conf): def pymol_scraper(block, block_vars, gallery_conf): _, code, _ = block block_conf = extract_file_config(code) - # Search for a `sphinx_gallery_pymol_image` command + # Search for a `sphinx_gallery_ammolite_script` command if PYMOL_IMAGE_COMMAND not in block_conf: return figure_rst([], gallery_conf['src_dir']) diff --git a/environment.yml b/environment.yml index 6317ebc69..144f7c8cf 100644 --- a/environment.yml +++ b/environment.yml @@ -24,7 +24,7 @@ dependencies: # Testing - mdtraj >=1.9.3 - pytest >=5.2 - # Interfaced software in biotite.application + # Interfaced software in biotite.application (can also be installed separately) - autodock-vina - clustalo - dssp