Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: Use pydata-sphinx-theme #2243

Merged
merged 4 commits into from
Jun 8, 2023
Merged

DOC: Use pydata-sphinx-theme #2243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c94b4af
DOC: Use pydata-sphinx-theme
pllim Jun 7, 2023
fed3563
Add cards to index page
pllim Jun 7, 2023
7239c1e
Remove iframe hardcoding so it scales
pllim Jun 8, 2023
aa72c15
DOC: Insert small logo next to title
pllim Jun 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .readthedocs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
version: 2

build:
os: ubuntu-20.04
os: ubuntu-22.04
apt_packages:
- graphviz
tools:
python: "3.9"
python: "3.11"
jobs:
post_checkout:
# Use `git log` to check if the latest commit contains "skip rtd" or "rtd skip",
Expand Down
74 changes: 74 additions & 0 deletions docs/_static/jdaviz.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
/* Main page overview cards */

.sd-card {
background: #fff;
border-radius: 0;
padding: 30px 10px 20px 10px;
margin: 10px 0px;
}

.sd-card .sd-card-header {
text-align: center;
}

.sd-card .sd-card-header .sd-card-text {
margin: 0px;
}

.sd-card .sd-card-img-top {
height: 52px;
width: 52px;
margin-left: auto;
margin-right: auto;
}

.sd-card .sd-card-header {
border: none;
background-color: white;
color: #150458 !important;
font-size: var(--pst-font-size-h5);
font-weight: bold;
padding: 2.5rem 0rem 0.5rem 0rem;
}

.sd-card .sd-card-footer {
border: none;
background-color: white;
}

.sd-card .sd-card-footer .sd-card-text {
max-width: 220px;
margin-left: auto;
margin-right: auto;
}

/* Dark theme tweaking */
html[data-theme=dark] .sd-card img[src*='.svg'] {
filter: invert(0.82) brightness(0.8) contrast(1.2);
}

/* Main index page overview cards */
html[data-theme=dark] .sd-card {
background-color:var(--pst-color-background);
}

html[data-theme=dark] .sd-shadow-sm {
box-shadow: 0 .1rem 1rem rgba(250, 250, 250, .6) !important
}

html[data-theme=dark] .sd-card .sd-card-header {
background-color:var(--pst-color-background);
color: #150458 !important;
}

html[data-theme=dark] .sd-card .sd-card-footer {
background-color:var(--pst-color-background);
}

html[data-theme=dark] h1 {
color: var(--pst-color-primary);
}

html[data-theme=dark] h3 {
color: #0a6774;
}
101 changes: 49 additions & 52 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,42 +25,32 @@
# Thus, any C-extensions that are needed to build the documentation will *not*
# be accessible, and the documentation will not build correctly.

import os
import sys
import datetime
import importlib.metadata as importlib_metadata

from pathlib import Path

if sys.version_info < (3, 11):
import tomli as tomllib
else:
import tomllib
from jdaviz import __version__

try:
from sphinx_astropy.conf.v1 import * # noqa
from sphinx_astropy.conf.v2 import * # noqa
except ImportError:
print('ERROR: the documentation requires the sphinx-astropy package to be installed')
sys.exit(1)

with open(Path(__file__).parent.parent / "pyproject.toml", "rb") as configuration_file:
metadata = tomllib.load(configuration_file)

# -- General configuration ----------------------------------------------------

# By default, highlight as Python 3.
highlight_language = 'python3'

# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.2'
# needs_sphinx = '1.2'

# To perform a Sphinx version check that needs to be more specific than
# major.minor, call `check_sphinx_version("x.y.z")` here.
# check_sphinx_version("1.2.1")

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns.append('_templates')
exclude_patterns.append('_templates') # noqa: F405

# This is added to the end of RST files - a good place to put substitutions to
# be used globally.
Expand Down Expand Up @@ -134,13 +124,13 @@
.. |icon-viewer-data-select| image:: /img/icons/viewer_data_select.png
:scale: 30
:alt: data select icon
"""
""" # noqa: F405

# -- Project information ------------------------------------------------------

# This does not *have* to match the package name, but typically does
project = metadata['project']['name']
author = metadata['project']['authors'][0]['name']
project = "jdaviz"
author = "JDADF Developers"
copyright = '{0}, {1}'.format(
datetime.datetime.now().year, author)

Expand All @@ -149,15 +139,15 @@
# built documents.

# The full version, including alpha/beta/rc tags.
release = importlib_metadata.version(project)
release = __version__
dev = "dev" in release
# The short X.Y version.
version = '.'.join(release.split('.')[:2])

extensions += ['sphinx.ext.extlinks']
extensions += ['sphinx.ext.extlinks', 'sphinx_design'] # noqa: F405
gh_tag = f'v{release}' if '.dev' not in release else 'main'
extlinks = {'gh-tree': (f'https://github.com/spacetelescope/jdaviz/tree/{gh_tag}/%s', '%s'),
'gh-notebook': (f'https://github.com/spacetelescope/jdaviz/blob/{gh_tag}/notebooks/%s.ipynb',
'%s notebook')}
'gh-notebook': (f'https://github.com/spacetelescope/jdaviz/blob/{gh_tag}/notebooks/%s.ipynb', '%s notebook')} # noqa: E501

# -- Options for HTML output --------------------------------------------------

Expand All @@ -168,33 +158,54 @@
# variables set in the global configuration. The variables set in the
# global configuration are listed below, commented out.

html_css_files = ["jdaviz.css"]
html_copy_source = False

html_theme_options.update( # noqa: F405
{
"github_url": "https://github.com/spacetelescope/jdaviz",
"external_links": [
{"name": "Help Desk", "url": "http://jwsthelp.stsci.edu/"},
],
"use_edit_page_button": True,
}
)

html_context = {
"default_mode": "light",
"to_be_indexed": ["stable", "latest"],
"is_development": dev,
"github_user": "spacetelescope",
"github_repo": "jdaviz",
"github_version": "main",
"doc_path": "docs",
}

# Add any paths that contain custom themes here, relative to this directory.
# To use a different custom theme, add the directory containing the theme.
#html_theme_path = []
# html_theme_path = []

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. To override the custom theme, set this to the
# name of a builtin theme or the name of a custom theme in html_theme_path.
#html_theme = None

html_theme = "sphinx_rtd_theme"
# html_theme = "sphinx_rtd_theme"

# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# html_sidebars = {}

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = ''
html_logo = 'logos/jdaviz.svg'

# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = ''
html_favicon = 'logos/specviz2d.ico'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmmm, do we have any general jdaviz icon we can use?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is not a question I can answer. I could not find one in the current logo stash.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Jenneh - do you have anything (or can easily modify anything) for this? Its the icon that shows on the tabs in the browser, so needs to be square and work well at small sizes.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(but doesn't need to block this PR, using specviz2d logo is still more appropriate than the astropy logo that used to be there - although I am seeing a white instead of transparent background which would also be nice to fix)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what about the icon thats currently on the left hand side of the top menu, the one that says 'jdaviz' and has the 4 little icons under it (why not 5, by the way?)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keep in mind that this icon goes on the browser tab. There is very little space, so a full Jdaviz logo would be illegible.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why not 5, by the way?

I think the 5th is a combination of the other two? 🤷


# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = ''
# html_last_updated_fmt = ''

# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
Expand All @@ -220,21 +231,6 @@
[author], 1)]


# -- Options for the edit_on_github extension ---------------------------------

if metadata['tool']['build_sphinx']['edit_on_github']:

extensions += ['sphinx_astropy.ext.edit_on_github']

edit_on_github_project = metadata['tool']['build_sphinx']['github_project']
edit_on_github_branch = "main"

edit_on_github_source_root = ""
edit_on_github_doc_root = "docs"

# -- Resolving issue number to links in changelog -----------------------------
github_issues_url = 'https://github.com/{0}/issues/'.format(metadata['tool']['build_sphinx']['github_project'])

# -- Turn on nitpicky mode for sphinx (to warn about references not found) ----
nitpicky = True

Expand Down Expand Up @@ -263,15 +259,16 @@
nitpick_ignore.append((dtype, target))

# Extra intersphinx in addition to what is already in sphinx-astropy
intersphinx_mapping['glue'] = ('http://docs.glueviz.org/en/stable/', None)
intersphinx_mapping['glue_jupyter'] = ('https://glue-jupyter.readthedocs.io/en/stable/', None)
intersphinx_mapping['regions'] = ('https://astropy-regions.readthedocs.io/en/stable/', None)
intersphinx_mapping['skimage'] = ('https://scikit-image.org/docs/stable/', None)
intersphinx_mapping['specutils'] = ('https://specutils.readthedocs.io/en/stable/', None)
intersphinx_mapping['specreduce'] = ('https://specreduce.readthedocs.io/en/stable/', None)
intersphinx_mapping['photutils'] = ('https://photutils.readthedocs.io/en/stable/', None)
intersphinx_mapping['traitlets'] = ('https://traitlets.readthedocs.io/en/stable/', None)
intersphinx_mapping['roman_datamodels'] = ('https://roman-datamodels.readthedocs.io/en/stable/', None)
intersphinx_mapping.update({ # noqa: F405
'glue': ('http://docs.glueviz.org/en/stable/', None),
'glue_jupyter': ('https://glue-jupyter.readthedocs.io/en/stable/', None),
'photutils': ('https://photutils.readthedocs.io/en/stable/', None),
'regions': ('https://astropy-regions.readthedocs.io/en/stable/', None),
'roman_datamodels': ('https://roman-datamodels.readthedocs.io/en/stable/', None),
'skimage': ('https://scikit-image.org/docs/stable/', None),
'specreduce': ('https://specreduce.readthedocs.io/en/stable/', None),
'specutils': ('https://specutils.readthedocs.io/en/stable/', None),
'traitlets': ('https://traitlets.readthedocs.io/en/stable/', None)})

# Options for linkcheck
linkcheck_ignore = ['https://github.com/spacetelescope/jdaviz/settings/branches']
8 changes: 4 additions & 4 deletions docs/cubeviz/examples.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,25 +18,25 @@ Open and Explore a Cube

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/Xjo8jQPa0M0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe src="https://www.youtube.com/embed/Xjo8jQPa0M0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Selecting Subsets
=================

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/G4oFVhxWu5I" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe src="https://www.youtube.com/embed/G4oFVhxWu5I" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Model Fitting
=============

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/mxh7kjfvd5g" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe src="https://www.youtube.com/embed/mxh7kjfvd5g" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Line Analysis
=============

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/STREWC6ugOI" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe src="https://www.youtube.com/embed/STREWC6ugOI" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
11 changes: 5 additions & 6 deletions docs/cubeviz/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@

.. image:: ../logos/cubeviz.svg
:width: 400
.. |cubeviz_logo| image:: ../logos/cube.svg
:height: 42px

.. _cubeviz:

#######
Cubeviz
#######
######################
|cubeviz_logo| Cubeviz
######################

.. image:: https://stsci.box.com/shared/static/esod50xtbn07wvls1ia07urnr65tv2bj.gif
:alt: Introductory video tour of the Cubeviz configuration and its features
Expand Down
6 changes: 3 additions & 3 deletions docs/dev/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
##########
Developers
##########
###############
Developer Guide
###############

Here is some documentation specific for developers.

Expand Down
10 changes: 5 additions & 5 deletions docs/imviz/examples.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,32 +18,32 @@ Open Image Data

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/WPe3XCZQGxs" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe src="https://www.youtube.com/embed/WPe3XCZQGxs" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Overplotting a Catalog
======================

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/2OUuxxNkkbM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe src="https://www.youtube.com/embed/2OUuxxNkkbM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Aligning Images
===============

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/vZHiuDuKheQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe src="https://www.youtube.com/embed/vZHiuDuKheQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Exploring the Plugin Toolbar
============================

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/3GD8W6QT634" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe src="https://www.youtube.com/embed/3GD8W6QT634" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Aperture Photometry
===================

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/hDoGvJIHby4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe src="https://www.youtube.com/embed/hDoGvJIHby4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
10 changes: 5 additions & 5 deletions docs/imviz/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
.. image:: ../logos/imviz.svg
:width: 400
.. |imviz_logo| image:: ../logos/imviz\ icon.svg
:height: 42px

.. _imviz:

#####
Imviz
#####
##################
|imviz_logo| Imviz
##################

.. image:: https://stsci.box.com/shared/static/56jhed2cqr3nr2w5a3e5gwwkvytmc00n.gif
:alt: Introductory video tour of the Imviz configuration and its features
Expand Down
Loading