Fix refernces in CONTRIBUTING.rst

CONTRIBUTING.rst

@@ -2,9 +2,10 @@
     - This file summarizes Python dev conventions for this project.
     - Refer to 'Vision' for project aims and 'Documentation' for naming conventions.
     - Only modify  CONTRIBUTING.rst and then update the /docs/source/index/CONTRIBUTING_COPY.rst.
+    - Remove '/docs/source' from image paths for CONTRIBUTING_COPY.
     Some minor doc tools
-    - You can use Traffic analytics (https://docs.readthedocs.io/en/stable/analytics.html) for doc traffic
-    - Check URLs with LinkChecker (bash: linkchecker ./docs/_build/html/index.html)
+    - You can use Traffic analytics (https://docs.readthedocs.io/en/stable/analytics.html) for doc traffic.
+    - Check URLs with LinkChecker (bash: linkchecker ./docs/_build/html/index.html).
 
 ============
 Contributing
@@ -234,12 +235,11 @@ See the reference order in this image:
 
 .. image :: /docs/source/_artwork/diagrams/ref_order.png
 
-The :doc:`API <api>` specifically highlights the **docstrings** for our public objects and functions.
-Within these docstrings, scientific :doc:`References` may be mentioned in their extended sections.
-Additional references should be organized in the *See Also* section in this sequence: :doc:`Usage Principles`,
-:doc:`Tutorials`, and :doc:`Tables`. **External library** links are to be included only when crucial.
-Note that the Usage Principles can freely reference :doc:`References`, :doc:`Tutorials`, and :doc:`Tables`.
-
+The :ref:`API <api>` showcases **docstrings** for our public objects and functions. Within these docstrings, scientific
+:ref:`References <references>` may be mentioned in their extended sections. For additional links in docstrings,
+use the *See Also* section in this order:  :ref:`Usage Principles <usage_principles>`, :ref:`Tutorials <tutorials>`,
+:ref:`Tables <tables>`. Only include **External library** references when absolutely necessary. Note that the
+Usage Principles documentation is open for direct linking to References, Tutorials, and Tables.
 
 Building the Docs
 -----------------

docs/build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 73327e7529e39e18692ad366f3953c23
+config: 4b53e89afed8466253c208f08dd314dd
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/_sources/api.rst.txt

@@ -1,19 +1,19 @@
 .. currentmodule:: aaanalysis
 
+.. _api:
+
 ===
 API
 ===
 
-This page contains the API reference for public objects and functions in AAanalysis. See more examples
-and practical usage in our :ref:`tutorials <tutorials>`.
-
-For convenience, it is common to import the module as follows:
+This Application Programming Interface (API) is the public interface for the objects and functions of our AAanalysis
+Python toolkit, which can be imported by:
 
 .. code-block:: python
 
     import aaanalysis as aa
 
-Then you can access all methods and objects via the `aa` alias, such as `aa.load_dataset`.
+You can then access all methods and objects via the `aa` alias, such as `aa.load_dataset`.
 
 .. _data_api:
 

docs/build/html/_sources/index/CONTRIBUTING_COPY.rst.txt

@@ -2,9 +2,10 @@
     - This file summarizes Python dev conventions for this project.
     - Refer to 'Vision' for project aims and 'Documentation' for naming conventions.
     - Only modify  CONTRIBUTING.rst and then update the /docs/source/index/CONTRIBUTING_COPY.rst.
+    - Remove '/docs/source' from image paths for CONTRIBUTING_COPY.
     Some minor doc tools
-    - You can use Traffic analytics (https://docs.readthedocs.io/en/stable/analytics.html) for doc traffic
-    - Check URLs with LinkChecker (bash: linkchecker ./docs/_build/html/index.html)
+    - You can use Traffic analytics (https://docs.readthedocs.io/en/stable/analytics.html) for doc traffic.
+    - Check URLs with LinkChecker (bash: linkchecker ./docs/_build/html/index.html).
 
 ============
 Contributing
@@ -230,6 +231,15 @@ This project's documentation is organized across four distinct layers, each with
 
 - **Tables**:  Close-up on data or other tabular overviews, with detailed explanation of columns and critical values.
 
+See the reference order in this image:
+
+.. image :: /_artwork/diagrams/ref_order.png
+
+The :ref:`API <api>` showcases **docstrings** for our public objects and functions. Within these docstrings, scientific
+:ref:`References <references>` may be mentioned in their extended sections. For additional links in docstrings,
+use the *See Also* section in this order:  :ref:`Usage Principles <usage_principles>`, :ref:`Tutorials <tutorials>`,
+:ref:`Tables <tables>`. Only include **External library** references when absolutely necessary. Note that the
+Usage Principles documentation is open for direct linking to References, Tutorials, and Tables.
 
 Building the Docs
 -----------------

docs/build/html/_sources/index/introduction.rst.txt

@@ -12,3 +12,7 @@ A typical workflow consists of the following steps:
 - **AAclust**: k-optimized clustering wrapper framework to select redundancy-reduced sets of numerical scales (e.g., amino acid scales)
 - **CPP**: Comparative Physicochemical Profiling, a feature engineering algorithm comparing two sets of protein sequences to identify the set of most distinctive features.
 - **dPULearn**: deterministic Positive-Unlabeled (PU) Learning algorithm to enable training on unbalanced and small datasets.
+
+Overview of documentation
+-------------------------
+See examples and practical usage in our :ref:`tutorials <tutorials>`.

docs/build/html/_sources/index/references.rst.txt

@@ -1,3 +1,25 @@
+..
+   Developer Note:
+
+   This RST document lists references for the project, organized into four sections:
+
+   1. **Algorithms**: For algorithm-based references.
+   2. **Datasets and Benchmarks**: For dataset and benchmark tool references.
+   3. **Use Cases**: Currently empty but reserved for application-related references.
+   4. **Further Information**: For any additional, miscellaneous references.
+
+   To add a new citation:
+
+   1. Choose the appropriate section.
+   2. Add a unique citation identifier (e.g., `[Breimann23a]`).
+   3. Provide the full citation, followed by the optional link if available. Use the syntax `.. [CitationID]` for
+   the citation and `` `Title <URL>`__ `` for the link.
+
+   Make sure to update all related documents that need to reference the new citation.
+..
+
+.. _references:
+
 References
 ==========
 

docs/build/html/_sources/index/tables.rst.txt

@@ -20,6 +20,8 @@
    ADD-TABLE: Placeholder indicating where tables for the corresponding section should be inserted.
 ..
 
+.. _tables:
+
 Tables
 ======
 

docs/build/html/_sources/index/usage_principles.rst.txt

@@ -11,6 +11,8 @@
    Always include brief code examples that mirror the corresponding usage examples.
 ..
 
+.. _usage_principles:
+
 Usage Principles
 ================
 To get started with AAanalysis, import it as follows:

docs/build/html/api.html

@@ -6,12 +6,12 @@
 <meta property="og:type" content="website" />
 <meta property="og:url" content="api.html" />
 <meta property="og:site_name" content="AAanalysis" />
-<meta property="og:description" content="This page contains the API reference for public objects and functions in AAanalysis. See more examples and practical usage in our tutorials. For convenience, it is common to import the module as fo..." />
+<meta property="og:description" content="This Application Programming Interface (API) is the public interface for the objects and functions of our AAanalysis Python toolkit, which can be imported by: You can then access all methods and ob..." />
 <meta property="og:image:width" content="1146" />
 <meta property="og:image:height" content="600" />
-<meta property="og:image" content="/_images/social_previews/summary_api_5f49419e.png" />
-<meta property="og:image:alt" content="This page contains the API reference for public objects and functions in AAanalysis. See more examples and practical usage in our tutorials. For convenience,..." />
-<meta name="description" content="This page contains the API reference for public objects and functions in AAanalysis. See more examples and practical usage in our tutorials. For convenience, it is common to import the module as fo..." />
+<meta property="og:image" content="/_images/social_previews/summary_api_d0528d29.png" />
+<meta property="og:image:alt" content="This Application Programming Interface (API) is the public interface for the objects and functions of our AAanalysis Python toolkit, which can be imported by..." />
+<meta name="description" content="This Application Programming Interface (API) is the public interface for the objects and functions of our AAanalysis Python toolkit, which can be imported by: You can then access all methods and ob..." />
 <meta name="twitter:card" content="summary_large_image" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
@@ -140,14 +140,13 @@
            <div itemprop="articleBody">
 
   <section id="api">
-<h1>API<a class="headerlink" href="#api" title="Permalink to this heading"></a></h1>
-<p>This page contains the API reference for public objects and functions in AAanalysis. See more examples
-and practical usage in our <a class="reference internal" href="tutorials.html#tutorials"><span class="std std-ref">tutorials</span></a>.</p>
-<p>For convenience, it is common to import the module as follows:</p>
+<span id="id1"></span><h1>API<a class="headerlink" href="#api" title="Permalink to this heading"></a></h1>
+<p>This Application Programming Interface (API) is the public interface for the objects and functions of our AAanalysis
+Python toolkit, which can be imported by:</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">aaanalysis</span> <span class="k">as</span> <span class="nn">aa</span>
 </pre></div>
 </div>
-<p>Then you can access all methods and objects via the <cite>aa</cite> alias, such as <cite>aa.load_dataset</cite>.</p>
+<p>You can then access all methods and objects via the <cite>aa</cite> alias, such as <cite>aa.load_dataset</cite>.</p>
 <section id="data">
 <span id="data-api"></span><h2>Data<a class="headerlink" href="#data" title="Permalink to this heading"></a></h2>
 <table class="autosummary longtable docutils align-default">

docs/build/html/index/CONTRIBUTING_COPY.html

@@ -343,6 +343,13 @@ <h3>Documentation Layers<a class="headerlink" href="#documentation-layers" title
 <li><p><strong>Tutorial</strong>: Close-up on public interface, as step-by-step guide on essential usage with medium detail.</p></li>
 <li><p><strong>Tables</strong>:  Close-up on data or other tabular overviews, with detailed explanation of columns and critical values.</p></li>
 </ul>
+<p>See the reference order in this image:</p>
+<img alt="../_images/ref_order.png" src="../_images/ref_order.png" />
+<p>The <a class="reference internal" href="../api.html#api"><span class="std std-ref">API</span></a> showcases <strong>docstrings</strong> for our public objects and functions. Within these docstrings, scientific
+<a class="reference internal" href="references.html#references"><span class="std std-ref">References</span></a> may be mentioned in their extended sections. For additional links in docstrings,
+use the <em>See Also</em> section in this order:  <a class="reference internal" href="usage_principles.html#usage-principles"><span class="std std-ref">Usage Principles</span></a>, <a class="reference internal" href="../tutorials.html#tutorials"><span class="std std-ref">Tutorials</span></a>,
+<a class="reference internal" href="tables.html#tables"><span class="std std-ref">Tables</span></a>. Only include <strong>External library</strong> references when absolutely necessary. Note that the
+Usage Principles documentation is open for direct linking to References, Tutorials, and Tables.</p>
 </section>
 <section id="building-the-docs">
 <h3>Building the Docs<a class="headerlink" href="#building-the-docs" title="Permalink to this heading"></a></h3>

docs/build/html/index/introduction.html

@@ -72,6 +72,7 @@
 <ul class="current">
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Introduction</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#workflow">Workflow</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#overview-of-documentation">Overview of documentation</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="usage_principles.html">Usage Principles</a></li>
@@ -128,6 +129,10 @@ <h2>Workflow<a class="headerlink" href="#workflow" title="Permalink to this head
 <li><p><strong>dPULearn</strong>: deterministic Positive-Unlabeled (PU) Learning algorithm to enable training on unbalanced and small datasets.</p></li>
 </ul>
 </section>
+<section id="overview-of-documentation">
+<h2>Overview of documentation<a class="headerlink" href="#overview-of-documentation" title="Permalink to this heading"></a></h2>
+<p>See examples and practical usage in our <a class="reference internal" href="../tutorials.html#tutorials"><span class="std std-ref">tutorials</span></a>.</p>
+</section>
 </section>
 
 

docs/build/html/index/references.html

@@ -117,7 +117,7 @@
            <div itemprop="articleBody">
 
   <section id="references">
-<h1>References<a class="headerlink" href="#references" title="Permalink to this heading"></a></h1>
+<span id="id1"></span><h1>References<a class="headerlink" href="#references" title="Permalink to this heading"></a></h1>
 <section id="algorithms">
 <h2>Algorithms<a class="headerlink" href="#algorithms" title="Permalink to this heading"></a></h2>
 <div role="list" class="citation-list">

docs/build/html/index/tables.html

@@ -117,16 +117,16 @@
            <div itemprop="articleBody">
 
   <section id="tables">
-<h1>Tables<a class="headerlink" href="#tables" title="Permalink to this heading"></a></h1>
+<span id="id1"></span><h1>Tables<a class="headerlink" href="#tables" title="Permalink to this heading"></a></h1>
 <nav class="contents local" id="contents">
 <ul class="simple">
-<li><p><a class="reference internal" href="#overview-table" id="id1">Overview Table</a></p></li>
-<li><p><a class="reference internal" href="#protein-benchmark-datasets" id="id2">Protein Benchmark Datasets</a></p></li>
-<li><p><a class="reference internal" href="#amino-acid-scale-datasets" id="id3">Amino Acid Scale Datasets</a></p></li>
+<li><p><a class="reference internal" href="#overview-table" id="id2">Overview Table</a></p></li>
+<li><p><a class="reference internal" href="#protein-benchmark-datasets" id="id3">Protein Benchmark Datasets</a></p></li>
+<li><p><a class="reference internal" href="#amino-acid-scale-datasets" id="id4">Amino Acid Scale Datasets</a></p></li>
 </ul>
 </nav>
 <section id="overview-table">
-<span id="t0-mapper"></span><h2><a class="toc-backref" href="#id1" role="doc-backlink">Overview Table</a><a class="headerlink" href="#overview-table" title="Permalink to this heading"></a></h2>
+<span id="t0-mapper"></span><h2><a class="toc-backref" href="#id2" role="doc-backlink">Overview Table</a><a class="headerlink" href="#overview-table" title="Permalink to this heading"></a></h2>
 <p>All tables from the AAanalysis documentation are listed here, in chronological order based on the project history.</p>
 <table class="docutils align-default">
 <colgroup>
@@ -153,7 +153,7 @@ <h1>Tables<a class="headerlink" href="#tables" title="Permalink to this heading"
 </table>
 </section>
 <section id="protein-benchmark-datasets">
-<span id="t1-overview-benchmarks"></span><h2><a class="toc-backref" href="#id2" role="doc-backlink">Protein Benchmark Datasets</a><a class="headerlink" href="#protein-benchmark-datasets" title="Permalink to this heading"></a></h2>
+<span id="t1-overview-benchmarks"></span><h2><a class="toc-backref" href="#id3" role="doc-backlink">Protein Benchmark Datasets</a><a class="headerlink" href="#protein-benchmark-datasets" title="Permalink to this heading"></a></h2>
 <p>Three types of benchmark datasets are provided:</p>
 <ul class="simple">
 <li><p>Residue prediction (AA): Datasets used to predict specific properties of amino acid residues.</p></li>
@@ -348,7 +348,7 @@ <h1>Tables<a class="headerlink" href="#tables" title="Permalink to this heading"
 </table>
 </section>
 <section id="amino-acid-scale-datasets">
-<span id="t2-overview-scales"></span><h2><a class="toc-backref" href="#id3" role="doc-backlink">Amino Acid Scale Datasets</a><a class="headerlink" href="#amino-acid-scale-datasets" title="Permalink to this heading"></a></h2>
+<span id="t2-overview-scales"></span><h2><a class="toc-backref" href="#id4" role="doc-backlink">Amino Acid Scale Datasets</a><a class="headerlink" href="#amino-acid-scale-datasets" title="Permalink to this heading"></a></h2>
 <p>Various amino acid scale datasets are provided.</p>
 <table class="docutils align-default">
 <colgroup>

docs/build/html/index/usage_principles.html

@@ -119,7 +119,7 @@
            <div itemprop="articleBody">
 
   <section id="usage-principles">
-<h1>Usage Principles<a class="headerlink" href="#usage-principles" title="Permalink to this heading"></a></h1>
+<span id="id1"></span><h1>Usage Principles<a class="headerlink" href="#usage-principles" title="Permalink to this heading"></a></h1>
 <p>To get started with AAanalysis, import it as follows:</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">aaanalysis</span> <span class="k">as</span> <span class="nn">aa</span>
 </pre></div>

docs/source/api.rst

@@ -1,5 +1,7 @@
 .. currentmodule:: aaanalysis
 
+.. _api:
+
 ===
 API
 ===

docs/source/index/CONTRIBUTING_COPY.rst

@@ -2,9 +2,10 @@
     - This file summarizes Python dev conventions for this project.
     - Refer to 'Vision' for project aims and 'Documentation' for naming conventions.
     - Only modify  CONTRIBUTING.rst and then update the /docs/source/index/CONTRIBUTING_COPY.rst.
+    - Remove '/docs/source' from image paths for CONTRIBUTING_COPY.
     Some minor doc tools
-    - You can use Traffic analytics (https://docs.readthedocs.io/en/stable/analytics.html) for doc traffic
-    - Check URLs with LinkChecker (bash: linkchecker ./docs/_build/html/index.html)
+    - You can use Traffic analytics (https://docs.readthedocs.io/en/stable/analytics.html) for doc traffic.
+    - Check URLs with LinkChecker (bash: linkchecker ./docs/_build/html/index.html).
 
 ============
 Contributing
@@ -230,6 +231,15 @@ This project's documentation is organized across four distinct layers, each with
 
 - **Tables**:  Close-up on data or other tabular overviews, with detailed explanation of columns and critical values.
 
+See the reference order in this image:
+
+.. image :: /_artwork/diagrams/ref_order.png
+
+The :ref:`API <api>` showcases **docstrings** for our public objects and functions. Within these docstrings, scientific
+:ref:`References <references>` may be mentioned in their extended sections. For additional links in docstrings,
+use the *See Also* section in this order:  :ref:`Usage Principles <usage_principles>`, :ref:`Tutorials <tutorials>`,
+:ref:`Tables <tables>`. Only include **External library** references when absolutely necessary. Note that the
+Usage Principles documentation is open for direct linking to References, Tutorials, and Tables.
 
 Building the Docs
 -----------------

docs/source/index/references.rst

@@ -1,3 +1,25 @@
+..
+   Developer Note:
+
+   This RST document lists references for the project, organized into four sections:
+
+   1. **Algorithms**: For algorithm-based references.
+   2. **Datasets and Benchmarks**: For dataset and benchmark tool references.
+   3. **Use Cases**: Currently empty but reserved for application-related references.
+   4. **Further Information**: For any additional, miscellaneous references.
+
+   To add a new citation:
+
+   1. Choose the appropriate section.
+   2. Add a unique citation identifier (e.g., `[Breimann23a]`).
+   3. Provide the full citation, followed by the optional link if available. Use the syntax `.. [CitationID]` for
+   the citation and `` `Title <URL>`__ `` for the link.
+
+   Make sure to update all related documents that need to reference the new citation.
+..
+
+.. _references:
+
 References
 ==========
 

docs/source/index/tables.rst

@@ -20,6 +20,8 @@
    ADD-TABLE: Placeholder indicating where tables for the corresponding section should be inserted.
 ..
 
+.. _tables:
+
 Tables
 ======
 

docs/source/index/tables_template.rst

@@ -20,6 +20,8 @@
    ADD-TABLE: Placeholder indicating where tables for the corresponding section should be inserted.
 ..
 
+.. _tables_XXX:
+
 Tables
 ======
 

docs/source/index/usage_principles.rst

@@ -11,6 +11,8 @@
    Always include brief code examples that mirror the corresponding usage examples.
 ..
 
+.. _usage_principles:
+
 Usage Principles
 ================
 To get started with AAanalysis, import it as follows: