Skip to content

Commit

Permalink
Merge pull request #391 from GreenBankObservatory/docs-redesign-gbtdocs
Browse files Browse the repository at this point in the history
Redesign of the docs
  • Loading branch information
astrofle authored Oct 22, 2024
2 parents c2cb37c + fbebf0d commit 7ba4daf
Show file tree
Hide file tree
Showing 31 changed files with 668 additions and 154 deletions.
104 changes: 94 additions & 10 deletions docs/source/_static/css/custom.css
Original file line number Diff line number Diff line change
@@ -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;
}
22 changes: 0 additions & 22 deletions docs/source/background/gbo_context.rst

This file was deleted.

Empty file.
11 changes: 0 additions & 11 deletions docs/source/background/index.rst

This file was deleted.

22 changes: 21 additions & 1 deletion docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@
"sphinxcontrib.mermaid",
"numpydoc",
"sphinx_inline_tabs",
"sphinx_design",
]

numpydoc_show_class_members = True
Expand All @@ -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"]

Expand All @@ -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"
Expand All @@ -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,
Expand Down
1 change: 0 additions & 1 deletion docs/source/examples

This file was deleted.

58 changes: 58 additions & 0 deletions docs/source/explanations/index.rst
Original file line number Diff line number Diff line change
@@ -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
42 changes: 42 additions & 0 deletions docs/source/explanations/scanblock/index.rst
Original file line number Diff line number Diff line change
@@ -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]
7 changes: 7 additions & 0 deletions docs/source/explanations/sdfits/index.rst
Original file line number Diff line number Diff line change
@@ -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>`_.
1 change: 1 addition & 0 deletions docs/source/for_developers/git_workflows.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
40 changes: 35 additions & 5 deletions docs/source/getting_started/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Loading

0 comments on commit 7ba4daf

Please sign in to comment.