Update documentation for SIST 1.0.0

docs/source/citation.rst

@@ -0,0 +1,57 @@
+Citing SIST
+===========
+
+Software citation
+-----------------
+
+SIST is currently maintained and developed by CCPBioSim.
+
+The repository provides a ``CITATION.cff`` file containing software citation
+metadata for the current SIST release.
+
+When using SIST in published work, cite the SIST software and the relevant
+scientific methods for the analyses performed.
+
+Scientific references
+---------------------
+
+When using the SIST algorithms, cite the following publication:
+
+Zhabinskaya, D., Madden, S., & Benham, C. J. (2015).
+"SIST: stress-induced structural transitions in superhelical DNA."
+*Bioinformatics*, 31(3), 421-422.
+
+The following publications describe the statistical-mechanical methods and
+algorithms used for the different structural transitions and should be cited
+as appropriate for the analyses performed.
+
+Fye, R. M. and Benham, C. J. (1999).
+"Exact method for numerically analyzing a model of local denaturation in
+superhelically stressed DNA."
+*Physical Review E*, 59, 3408-3426.
+
+Zhabinskaya, D. and Benham, C. J. (2011).
+"Theoretical Analysis of the Stress Induced BZ Transition in Superhelical DNA."
+*PLoS Computational Biology*, 7, 1-14.
+
+Zhabinskaya, D. and Benham, C. J. (2013).
+"Competitive superhelical transitions involving cruciform extrusion."
+*Nucleic Acids Research*, 41(21), 9610-9621.
+
+Contact
+-------
+
+SIST is currently maintained and developed by CCPBioSim.
+
+For questions, bug reports, or contributions relating to the maintained
+software, please use the `CCPBioSim SIST GitHub repository
+<https://github.com/CCPBioSim/SIST>`_.
+
+Original contacts
+-----------------
+
+The original SIST documentation listed the following contacts:
+
+* Dina Zhabinskaya - dzhabinskaya@ucdavis.edu
+* Craig Benham - cjbenham@ucdavis.edu
+* Sally Madden - sallymadden@gmail.com

docs/source/development.rst

@@ -0,0 +1,143 @@
+Development and Testing
+=======================
+
+The maintained development workflow validates both the source tree and the
+installed Conda package.
+
+Source build
+------------
+
+Build the C++ components from the repository root:
+
+.. code-block:: bash
+
+   make -C trans_three clean
+   make -C trans_three
+   make -C trans_compete clean
+   make -C trans_compete
+
+The Makefiles are also used by the Conda build and accept the compiler and
+linker settings supplied by the Conda toolchain.
+
+Source tests
+------------
+
+The pytest suite validates command-line behaviour and the maintained scientific
+reference outputs.
+
+Python 3.12 or later is supported for source testing. A direct source test run
+also requires:
+
+* GNU Make
+* a C++ compiler
+* Perl
+* IRF 3.08 on ``PATH``
+
+Install the Python testing dependencies:
+
+.. code-block:: bash
+
+   python -m pip install -e '.[testing]'
+
+Run the test suite:
+
+.. code-block:: bash
+
+   python -m pytest tests -vv
+
+During a normal source test run, the test fixtures create a temporary copy of
+the repository, build the C++ executables, and run the supported calculations
+from that working copy.
+
+Scientific regression baselines
+--------------------------------
+
+The maintained reference outputs for SIST 1.0.0 are stored under:
+
+.. code-block:: text
+
+   tests/reference/v1.0.0/
+
+The regression suite covers:
+
+* melting
+* Z-DNA
+* cruciform
+* competition
+
+The tests compare deterministic calculation metadata and profile values at the
+precision printed by SIST. Runtime is excluded from the scientific comparison.
+
+Reference outputs should only be changed as part of a reviewed scientific
+change. A failing regression test should not be resolved by replacing the
+reference output without establishing the reason for the difference.
+
+Conda package
+-------------
+
+The Conda recipe defines the package build, runtime, and test requirements.
+
+Build requirements
+~~~~~~~~~~~~~~~~~~
+
+* Conda C++ compiler
+* GNU Make
+
+Runtime requirements
+~~~~~~~~~~~~~~~~~~~~
+
+* Perl
+* IRF ``>=3.08,<3.09``
+* compiler runtime libraries resolved by Conda
+
+Package-test requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Python
+* pytest
+
+Python and pytest are package-test dependencies only; they are not required for
+normal use of the installed SIST package.
+
+Build and test the Conda package
+--------------------------------
+
+Build and test the package with:
+
+.. code-block:: bash
+
+   conda build conda-recipe \
+       --override-channels \
+       -c conda-forge \
+       -c bioconda \
+       --no-anaconda-upload
+
+``conda-build`` creates isolated build and test environments automatically.
+
+The package test verifies the installed ``sist`` command and its declared
+runtime dependencies before running the regression suite.
+
+The two validation paths therefore serve different purposes:
+
+``python -m pytest``
+   Builds and tests the maintained source tree.
+
+``conda build``
+   Builds the package and tests the installed ``sist`` command using the
+   dependencies declared by the Conda recipe.
+
+Release workflow
+----------------
+
+The release workflow prepares and publishes a SIST release by:
+
+1. validating the requested version
+2. updating the Conda recipe version
+3. updating ``CITATION.cff``
+4. creating the release tag
+5. creating the GitHub release
+6. building and testing the Conda package
+7. publishing the validated package to the CCPBioSim Anaconda channel
+
+The package published for a release is therefore built and tested from the same
+Conda recipe used during development and continuous integration.

docs/source/index.rst

@@ -1,19 +1,47 @@
-.. SIST documentation master file, created by
-   sphinx-quickstart on Thu Jan 22 14:14:31 2026.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+SIST
+====
 
-SIST documentation
-==================
+SIST (Stress-Induced Structural Transitions) is a program for analysing
+stress-induced structural transitions in superhelical DNA with a specified
+base sequence.
 
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
+SIST supports calculations for:
 
+* strand separation (melting/SIDD)
+* Z-DNA formation
+* cruciform extrusion
+* competition between melting, Z-DNA, and cruciform transitions
+
+SIST 1.0.0 provides a maintained Conda distribution, an installed ``sist``
+command, and regression testing against reference scientific outputs.
+
+Quick start
+-----------
+
+Install SIST with Conda:
+
+.. code-block:: bash
+
+   conda install -c ccpbiosim -c conda-forge -c bioconda sist
+
+Run a melting calculation:
+
+.. code-block:: bash
+
+   sist -a M -f sequence.fa
+
+Run a competition calculation and write the result to a file:
+
+.. code-block:: bash
+
+   sist -a A -f sequence.fa -o results.txt
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Contents
 
    user-guide
-
+   installation
+   source-usage
+   development
+   citation

docs/source/installation.rst

@@ -0,0 +1,75 @@
+Installation
+============
+
+Conda
+-----
+
+The recommended way to install SIST is with Conda:
+
+.. code-block:: bash
+
+   conda install -c ccpbiosim -c conda-forge -c bioconda sist
+
+The package installs the ``sist`` command together with the runtime
+dependencies required by SIST, including:
+
+* Perl
+* Inverted Repeats Finder (IRF)
+* the required C++ runtime libraries
+
+SIST 1.0.0 is validated with IRF 3.08, and the Conda package constrains the
+runtime dependency to ``>=3.08,<3.09``.
+
+Python and pytest are used for testing and are not required in a normal SIST
+runtime environment.
+
+Verify the installation
+-----------------------
+
+Confirm that the installed command and runtime dependencies are available:
+
+.. code-block:: bash
+
+   command -v sist
+   command -v perl
+   command -v irf
+
+The commands should resolve inside the active Conda environment.
+
+Running ``sist`` without the required arguments displays the command-line
+usage:
+
+.. code-block:: bash
+
+   sist
+
+Building from source
+--------------------
+
+SIST can also be built directly from the source repository.
+
+A source build requires:
+
+* a C++ compiler
+* GNU Make
+* Perl
+* IRF 3.08 available as ``irf`` on ``PATH``
+
+Build both C++ components from the repository root:
+
+.. code-block:: bash
+
+   make -C trans_three
+   make -C trans_compete
+
+The source-tree pipeline can then be run with:
+
+.. code-block:: bash
+
+   perl master.pl -a M -f sequence.fa
+
+For cruciform and competition calculations, IRF must be available on ``PATH``.
+
+The source build uses the same calculation modes and command-line parameters as
+the installed ``sist`` command. The Source Usage page describes the individual
+source components and direct component workflow in more detail.