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

Jump to bottom

Cleanup doc config #209

Merged
merged 4 commits into from
Apr 3, 2018
Merged

Cleanup doc config #209

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
6399068
MNT: Clean up conf.py
dopplershift Mar 31, 2018
bc6ff64
ENH: Replace "View source" with "Improve this page"
dopplershift Mar 31, 2018
5c847d3
ENH: Add Siphon logo to docs
dopplershift Mar 31, 2018
aa82dca
MNT: Update main index page
dopplershift Apr 2, 2018
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
18 changes: 18 additions & 0 deletions docs/_static/theme_override.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,21 @@ div[class^="highlight"] a {
div[class^="highlight"] a:hover {
background-color: #ABECFC;
}

.wy-nav-content {
max-width: 100%
}

/* For the link to edit the page on Github */
.source-link {
float: right;
}

/* Don't let the edit link disappear on mobile. */
@media screen and (max-width: 480px) {
.wy-breadcrumbs li.source-link {
float:none;
display: block;
margin-top: 20px;
}
}
20 changes: 20 additions & 0 deletions docs/_templates/breadcrumbs.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
{# Extend the RTD template to include links to Github instead of "View page
source" #}
{% extends "!breadcrumbs.html" %}


{% block breadcrumbs_aside %}
<li class="source-link">
{% if hasdoc(pagename) %}
{% if pagename.startswith("api/") or pagename.startswith("tutorials/") or pagename.startswith("examples/")%}
{% set title = "Suggested improvement for " + pagename %}
{% set body = "Please describe what could be improved about this page or the typo/mistake that you found:" %}
<a href="https://github.com/{{ github_repo }}/issues/new?title={{ title|urlencode }}&body={{ body|urlencode }}"
class="fa fa-github"> Improve this page</a>
{% else %}
<a href="https://github.com/{{ github_repo }}/edit/{{ github_version }}/{{ doc_path }}/{{ pagename }}{{ suffix }}"
class="fa fa-github"> Improve this page</a>
{% endif %}
{% endif %}
</li>
{% endblock %}
48 changes: 25 additions & 23 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,6 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# Siphon documentation build configuration file, created by
# sphinx-quickstart on Wed Apr 22 15:27:44 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
Expand All @@ -16,6 +13,8 @@
import sys
import os

import siphon

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
Expand All @@ -37,20 +36,10 @@
'sphinx.ext.intersphinx',
'sphinx.ext.mathjax',
'sphinx.ext.napoleon',
'sphinx_gallery.gen_gallery',
'sphinx.ext.viewcode'
'sphinx.ext.viewcode',
'sphinx_gallery.gen_gallery'
]

mathjax_path = 'https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
#autosummary_generate = True

# Set up mapping for other projects' docs
intersphinx_mapping = {
'python': ('https://docs.python.org/3/', None),
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
'requests': ('http://docs.python-requests.org/en/master/', None),
}

sphinx_gallery_conf = {
'doc_module': ('siphon',),
'reference_url': {
Expand All @@ -70,6 +59,12 @@
'.md': 'recommonmark.parser.CommonMarkParser',
}

# Set up mapping for other projects' docs
intersphinx_mapping = {
'python': ('https://docs.python.org/3/', None),
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
'requests': ('http://docs.python-requests.org/en/master/', None),
}

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Expand All @@ -92,9 +87,8 @@
# built documents.
#
# The short X.Y version.
import siphon
verinfo = siphon.__version__
version = verinfo.split('+')[0]
version = verinfo.split('+')[0].rsplit('.', 1)[0]
# The full version, including alpha/beta/rc tags.
release = verinfo

Expand All @@ -114,7 +108,7 @@

# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
default_role = 'autolink'

# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
Expand Down Expand Up @@ -159,19 +153,27 @@ def setup(app):
if 'sphinx_rtd_theme' in vars() and sphinx_rtd_theme.__version__ == '0.2.5b1.post1':
html_theme_options['versions'] = {'latest': '../latest', 'dev': '../dev'}

# Extra variables that will be available to the templates. Used to create the
# links to the Github repository sources and issues
html_context = {
'doc_path': 'docs',
'github_repo': 'Unidata/siphon',
'github_version': 'master', # Make changes to the master branch
}

# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []

# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
html_title = ' '.join((project, version))

# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
html_logo = os.path.join('_static', 'siphon_150x150.png')

# 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
Expand All @@ -190,7 +192,7 @@ def setup(app):

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
html_last_updated_fmt = '%b %d, %Y at %H:%M:%S'

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
Expand Down Expand Up @@ -281,7 +283,7 @@ def setup(app):
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'Siphon', 'Siphon Documentation',
['Unidata'], 1)
['Siphon Contributors'], 1)
]

# If true, show URL addresses after external links.
Expand All @@ -295,7 +297,7 @@ def setup(app):
# dir menu entry, description, category)
texinfo_documents = [
('index', 'Siphon', 'Siphon Documentation',
'Unidata', 'Siphon', 'One line description of project.',
'Siphon Contributors', 'Siphon', 'One line description of project.',
'Miscellaneous'),
]

Expand Down
15 changes: 3 additions & 12 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,3 @@
.. Siphon documentation master file, created by
sphinx-quickstart on Wed Apr 22 15:27:44 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

.. image:: _static/siphon_150x150.png
:width: 150 px
:align: left

.. toctree::
:maxdepth: 1
:hidden:
Expand All @@ -22,9 +13,9 @@
Siphon
======

Siphon is a collection of Python utilities for downloading data from Unidata
data technologies. Siphon's current functionality focuses on access to data hosted on a
`THREDDS Data Server`__.
Siphon is a collection of Python utilities for downloading data from remote
data services. Much of Siphon's current functionality focuses on access to
data hosted on a `THREDDS Data Server`__.

__ https://www.unidata.ucar.edu/software/thredds/current/tds/

Expand Down