Merge pull request #391 from GreenBankObservatory/docs-redesign-gbtdocs

Redesign of the docs
GreenBankObservatory · Oct 22, 2024 · 7ba4daf · 7ba4daf
2 parents c2cb37c + fbebf0d
commit 7ba4daf
Show file tree

Hide file tree

Showing 31 changed files with 668 additions and 154 deletions.
diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
@@ -1,11 +1,95 @@
 /* Remove width restriction on content so that diagrams
-   are more visible */
-   .wy-nav-content {
-      max-width: none;
-  }
-
-  /* Override the logo/searchbar background color;
-     it conflicts with the logo color */
-  .wy-side-nav-search {
-      background-color: #C6B9D2;
-  }
+are more visible */
+.wy-nav-content {
+  max-width: none;
+}
+
+/* Override the logo/searchbar background color;
+ it conflicts with the logo color */
+.wy-side-nav-search {
+  background-color: #C6B9D2;
+}
+
+.black {
+    color: black;
+}
+
+.gray {
+    color: gray;
+}
+
+.grey {
+    color: gray;
+}
+
+.silver {
+    color: silver;
+}
+
+.white {
+    color: white;
+}
+
+.maroon {
+    color: maroon;
+}
+
+.red {
+    color: red;
+}
+
+.magenta {
+    color: magenta;
+}
+
+.fuchsia {
+    color: fuchsia;
+}
+
+.pink {
+    color: pink;
+}
+
+.orange {
+    color: orange;
+}
+
+.yellow {
+    color: yellow;
+}
+
+.lime {
+    color: lime;
+}
+
+.green {
+    color: green;
+}
+
+.olive {
+    color: olive;
+}
+
+.teal {
+    color: teal;
+}
+
+.cyan {
+    color: cyan;
+}
+
+.aqua {
+    color: aqua;
+}
+
+.blue {
+    color: blue;
+}
+
+.navy {
+    color: navy;
+}
+
+.purple {
+    color: purple;
+}
diff --git a/docs/source/background/gbo_context.rst b/docs/source/background/gbo_context.rst
diff --git a/docs/source/background/img/.gitkeep b/docs/source/background/img/.gitkeep
diff --git a/docs/source/background/index.rst b/docs/source/background/index.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -58,6 +58,7 @@
     "sphinxcontrib.mermaid",
     "numpydoc",
     "sphinx_inline_tabs",
+    "sphinx_design",
 ]
 
 numpydoc_show_class_members = True
@@ -75,6 +76,11 @@
 # TODO: These appear to have no effect
 mermaid_verbose = True
 
+# Mermaid configuration
+# https://github.com/mgaitan/sphinxcontrib-mermaid
+mermaid_version = "11.2.0"
+mermaid_params = ["--theme", "dark"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -101,7 +107,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = []
+exclude_patterns = ["examples/output"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -120,11 +126,25 @@
 # documentation.
 #
 html_theme_options = {
+    "repository_url": "https://github.com/GreenBankObservatory/dysh",
+    "repository_branch": "main",
     "logo": {
         "image_light": "_static/icon/dysh_logo_lightmode.png",
         "image_dark": "_static/icon/dysh_logo_darkmode.png",
     },
+    # "show_toc_level": 2,
+    "use_source_button": True,
+    "use_issues_button": True,
+    "use_download_button": True,
+    "use_sidenotes": True,
     "show_toc_level": 2,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/GreenBankObservatory/dysh",
+            "icon": "fa-brands fa-github",
+        },
+    ],
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

diff --git a/docs/source/examples b/docs/source/examples
diff --git a/docs/source/explanations/index.rst b/docs/source/explanations/index.rst
@@ -0,0 +1,58 @@
+.. _explanations:
+
+###############################################
+:octicon:`repo;2em;purple` Explanation Material
+###############################################
+
+Big-picture explanations of higher-level concepts. Most useful for building understanding of a particular topic.
+
+dysh
+====
+
+.. grid:: 1 2 2 2
+
+    .. grid-item-card::
+        :shadow: md
+        :margin: 2 2 0 0
+
+        :octicon:`container;3em;green` **ScanBlock**
+
+        What is a ScanBlock?
+
+        .. button-link:: scanblock/index.html
+            :color: primary
+            :tooltip: Details of what is a ScanBlock
+            :outline:
+            :click-parent:
+
+            ScanBlock
+
+
+SDFITS
+======
+
+.. grid:: 1 2 2 2
+
+    .. grid-item-card::
+        :shadow: md
+        :margin: 2 2 0 0
+
+        :octicon:`file;3em;green` **SDFITS**
+
+        What are SDFITS files?
+
+        .. button-link:: sdfits/index.html
+            :color: primary
+            :tooltip: SDFITS details
+            :outline:
+            :click-parent:
+
+            SDFITS
+
+
+.. toctree::
+    :hidden:
+    :maxdepth: 3
+
+    scanblock/index
+    sdfits/index
diff --git a/docs/source/explanations/scanblock/index.rst b/docs/source/explanations/scanblock/index.rst
@@ -0,0 +1,42 @@
+.. _scanblocks:
+
+#########
+ScanBlock
+#########
+
+.. mermaid::
+
+    flowchart TD
+
+    subgraph newLines[GBTFITSLoad
+        50 Scans
+        Position Switching
+        Dual Linear Polarization
+        1 Beam
+        4 Frequency Windows
+        100 integrations each
+        ]
+
+
+
+
+    end
+
+
+    newLines -- getps( scan=45, plnum=1, ifnum=0 ) --> ScanBlock1
+    newLines -- gettp( scan=[17,18,19], intnum=np.r_[50:100], ifnum=2 ) --> ScanBlock2
+
+
+
+    subgraph ScanBlock1[ScanBlock]
+            psscan["spectra.scan.PSScan<br />scans = 44,45<br />plnum = 1<br />ifnum = 0<br />intnum = (0,100)"]
+        end
+    subgraph ScanBlock2[ScanBlock]
+            tpscan1["spectra.scan.TPScan<br />scan=17<br />plnum = 0<br />ifnum = 2<br />intnum=(50,100)"]
+            tpscan2["spectra.scan.TPScan<br />scan=18<br />plnum = 0<br />ifnum = 2<br />intnum=(50,100)"]
+            tpscan3["spectra.scan.TPScan<br />scan=19<br />plnum = 0<br />ifnum = 2<br />intnum=(50,100)"]
+
+        end
+
+    ScanBlock1[Scan Block] -- timeaverage() --->spectrum1[Spectrum]
+    ScanBlock2[Scan Block] -- timeaverage() --->spectrum2[Spectrum]
diff --git a/docs/source/explanations/sdfits/index.rst b/docs/source/explanations/sdfits/index.rst
@@ -0,0 +1,7 @@
+.. _sdfits-explanation:
+
+############
+SDFITS Files
+############
+
+This section is empty for now, but you can check the column definitions :ref:`here <sdfits-reference>`, or the SDFITS convention as defined in `AIPS++ <https://casa.nrao.edu/aips2_docs/notes/236/node14.html>`_ or at `ADASS IX <https://www.aspbooks.org/a/volumes/article_details/?paper_id=20663>`_, or `the registered SDFITS convention <https://fits.gsfc.nasa.gov/registry/sdfits.html>`_.
diff --git a/docs/source/for_developers/git_workflows.rst b/docs/source/for_developers/git_workflows.rst
@@ -55,6 +55,7 @@ In the directory you want to work in, set up the repo:
 To check out a branch called {{branch-name}}, just do
 
 .. code-block:: bash
+
     $ git checkout {{branch-name}}
 
 Current development is done in the `main` branch. To set up your own development branch called `{{your-name}}-devel`, do the following:

diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst
@@ -2,10 +2,40 @@
 Getting Started
 ***************
 
-Here's how you get started
+Installing ``dysh``
+===================
 
-.. toctree::
-    :maxdepth: 2
+``dysh`` requires Python 3.9+ and recent versions of
+`astropy <https://astropy.org>`_,
+`numpy <https://numpy.org>`_,
+`scipy <https://scipy.org>`_,
+`pandas <https://pandas.pydata.org>`_,
+`specutils <https://specutils.readthedocs.io/en/stable/>`_,  and
+`matplotlib <https://matplotlib.org>`_.
 
-    install
-    tutorials/index
+We strongly recommend the use of a virtual environment for installing `dysh`.
+
+With `pip` from PyPi
+--------------------
+
+``dysh`` is most easily installed with ``pip``, which will take care of
+any dependencies.  The packaged code is hosted at the `Python Packaging
+Index <https://pypi.org/project/dysh>`_.
+
+.. code::
+
+    $ pip install dysh
+
+.. warning::
+    `dysh` is currently in development and the above command will install the latest stable version of `dysh` which might not reflect the contents of the documentation.
+    For beta testing please see :ref:`beta-install`.
+
+From GitHub
+-----------
+
+Installing from GitHub will allow you to install the latest, albeit unstable, version of `dysh`.
+To install the main branch of `dysh` with all extra dependencies from GitHub:
+
+.. code::
+
+    $ pip install "dysh[all] @ git+https://github.com/GreenBankObservatory/dysh"