Merge pull request #215 from bacpop/api-doc-fix

Read the docs sphinx version
bacpop · Sep 13, 2022 · 6cce212 · 6cce212
2 parents 3b4ab31 + de1c496
commit 6cce212
Show file tree

Hide file tree

Showing 14 changed files with 25 additions and 51 deletions.
diff --git a/readthedocs.yml → .readthedocs.yaml b/readthedocs.yml → .readthedocs.yaml
diff --git a/docs/api.rst b/docs/api.rst
@@ -3,8 +3,9 @@ Reference documentation
 
 Documentation for module functions (for developers)
 
-.. contents::
-   :local:
+.. warning::
+    This doesn't build properly on readthedocs. To view, clone and run
+    ``cd docs && make html`` then see ``_build/api.html``.
 
 assign.py
 ---------

diff --git a/docs/conf.py b/docs/conf.py
@@ -26,7 +26,7 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+#needs_sphinx = '5.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -46,11 +46,15 @@
                         "sklearn",
                         "matplotlib",
                         "dendropy",
-                        "pp-sketchlib",
+                        "pp_sketchlib",
+                        "biopython",
+                        "Bio",
+                        "tqdm",
+                        "tqdm.tqdm",
+                        "SCE",
+                        "treeswift",
                         "poppunk_refine",
                         "h5py",
-                        "flask",
-                        "flask-cors",
                         "networkx"]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -84,7 +88,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -103,7 +107,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'furo'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -121,15 +125,15 @@
 #
 # This is required for the alabaster theme
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    '**': [
-        'about.html',
-        'navigation.html',
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
-        'donate.html',
-    ]
-}
+#html_sidebars = {
+#    '**': [
+#        'about.html',
+#        'navigation.html',
+#        'relations.html',  # needs 'show_related': True theme option to display
+#        'searchbox.html',
+#        'donate.html',
+#    ]
+#}
 
 
 # -- Options for HTMLHelp output ------------------------------------------

diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst
@@ -3,6 +3,7 @@ Miscellaneous
 
 Rejected/alternative logos
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. image:: images/poppunk_logo_original.png
    :alt:  Original logo
    :align: center

diff --git a/docs/model_fitting.rst b/docs/model_fitting.rst
@@ -14,9 +14,6 @@ on the population structure of your dataset.
     so others can use it for assigning queries. If you are open to this, please read
     :doc:`model_distribution` after this page.
 
-.. contents::
-   :local:
-
 Overview
 --------
 

diff --git a/docs/mst.rst b/docs/mst.rst
@@ -20,11 +20,6 @@ In each mode, you can get as output:
 - The graph as a graphml file, to view in :ref:`cytoscape-view`.
 - The MST formatted as a newick file, to view in a tree viewer of your choice.
 
-**Jump to**:
-
-.. contents::
-   :local:
-
 With small data
 ---------------
 For a small dataset it's feasible to find the MST from your (dense) distance matrix.

diff --git a/docs/online.rst b/docs/online.rst
@@ -8,9 +8,6 @@ using pre-optimised species-specific databases and default parameters.
    PopPUNK-web is temporarily down while we work on an updated and better supported
    version (beebop).
 
-.. contents::
-   :local:
-
 How it works
 ------------
 PopPUNK-web uses C++ code compiled to WebAssembly to sketch query sequences client side, then post this sketch to our Python backend running PopPUNK.

diff --git a/docs/overview.rst b/docs/overview.rst
@@ -3,9 +3,6 @@ Overview
 This page details the way in which we would advise that you *should* use and
 run PopPUNK, if possible.
 
-.. contents::
-   :local:
-
 .. image:: images/poppunk_flowchart.png
    :alt:  Flowchart for choosing how to use PopPUNK
    :align: center

diff --git a/docs/query_assignment.rst b/docs/query_assignment.rst
@@ -8,9 +8,6 @@ Briefly, `download your reference database <https://poppunk.net/pages/databases.
     poppunk_assign --db database --query qfile.txt \
     --output poppunk_clusters --threads 8
 
-.. contents::
-   :local:
-
 Downloading a database
 ----------------------
 Current PopPUNK databases can be found here: https://poppunk.net/pages/databases.html

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,2 +1,3 @@
 Cython>=0.26.1
-docutils<0.18
+sphinx>=5.0
+furo
diff --git a/docs/scripts.rst b/docs/scripts.rst
@@ -8,9 +8,6 @@ To use these scripts you will need to have a clone of the git repository, or the
 installed with the prefix 'poppunk' (e.g to run ``extract_distances.py``, run the command
 ``poppunk_extract_distances.py``).
 
-.. contents::
-   :local:
-
 Easy run mode
 -------------
 Previous versions of the software had an ``--easy-run`` mode which would run a pipeline of:

diff --git a/docs/sketching.rst b/docs/sketching.rst
@@ -8,9 +8,6 @@ mash, however the current version now requires `pp-sketchlib <https://github.com
 This page details options related to sketching and distance calculation, and is relevant
 to both :doc:`query_assignment` and :doc:`model_fitting`.
 
-.. contents::
-   :local:
-
 Overview
 --------
 Any input given to ``--r-files`` or ``--q-files`` will be sketched using the following

diff --git a/docs/subclustering.rst b/docs/subclustering.rst
@@ -1,11 +1,6 @@
 Subclustering with PopPIPE
 ==========================
 
-**Contents**:
-
-.. contents::
-   :local:
-
 Overview
 --------
 You can run `PopPIPE <https://github.com/johnlees/PopPIPE>`__ on your PopPUNK output,

diff --git a/docs/visualisation.rst b/docs/visualisation.rst
@@ -1,11 +1,6 @@
 Creating visualisations
 =======================
 
-**Contents**:
-
-.. contents::
-   :local:
-
 We have moved visualisation tools into their own program ``poppunk_visualise``, both
 to reinforce our commitment to UK spellings, and so that you can rerun visualisations
 with different outputs and settings without rerunning the other parts of the code.