Skip to content

Documentation homepage, use of panels for visibility to users #3884

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

Merged
rcomer merged 9 commits into from
Sep 29, 2020
Merged

Documentation homepage, use of panels for visibility to users #3884

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
35979b1
play with sphinx-panels
tkknight Sep 26, 2020
59eb820
added requirement for sphinx-panels
tkknight Sep 26, 2020
cf76196
added link to https://sphinx-panels.readthedocs.io/en/latest/
tkknight Sep 26, 2020
401014c
refined options
tkknight Sep 26, 2020
e24714f
button block
tkknight Sep 27, 2020
2a5b7d4
added dependency
tkknight Sep 27, 2020
99655e1
moved Iris API in sidebar. Panels streamlined
tkknight Sep 28, 2020
cf9ecd8
Fixed typos/wording
tkknight Sep 28, 2020
0d47a55
Review updates
tkknight Sep 28, 2020
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
1 change: 1 addition & 0 deletions docs/iris/src/common_links.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,4 @@
.. _conda: https://docs.conda.io/en/latest/
.. _sphinx: https://www.sphinx-doc.org/en/master/
.. _napolean: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html
.. _legacy documentation: https://scitools.org.uk/iris/docs/v2.4.0/
4 changes: 4 additions & 0 deletions docs/iris/src/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ def autolog(message):
"sphinx.ext.intersphinx",
"sphinx_copybutton",
"sphinx.ext.napoleon",
"sphinx_panels",
# TODO: Spelling extension disabled until the dependencies can be included
# "sphinxcontrib.spelling",
"sphinx_gallery.gen_gallery",
Expand All @@ -126,6 +127,9 @@ def autolog(message):
"generate_package_rst",
]

# -- panels extension ---------------------------------------------------------
# See https://sphinx-panels.readthedocs.io/en/latest/

# -- Napoleon extension -------------------------------------------------------
# See https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html
napoleon_google_docstring = True
Expand Down
4 changes: 2 additions & 2 deletions docs/iris/src/developers_guide/contributing_getting_involved.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _development_where_to_start:

.. include:: ../common_links.inc

.. _development_where_to_start:

Getting Involved
----------------

Expand Down
61 changes: 54 additions & 7 deletions docs/iris/src/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,3 @@
.. note:: For **Iris 2.4** and earlier documentation please see the
`legacy documentation`_

.. _legacy documentation: https://scitools.org.uk/iris/docs/v2.4.0/


Iris Documentation
==================

Expand Down Expand Up @@ -44,11 +38,61 @@ Interoperability with packages from the wider scientific Python ecosystem comes
from Iris' use of standard NumPy/dask arrays as its underlying data storage.

Iris is part of SciTools, for more information see https://scitools.org.uk/.
For **Iris 2.4** and earlier documentation please see the
:link-badge:`https://scitools.org.uk/iris/docs/v2.4.0/,"legacy documentation",cls=badge-info text-white`.


.. panels::
:container: container-lg pb-3
:column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2

Install Iris to use or for development.
+++
.. link-button:: installing_iris
:type: ref
:text: Installing Iris
:classes: btn-outline-primary btn-block
---
View the gallery that includes python code used to create it.
Copy link
Member

@rcomer rcomer Sep 28, 2020

Choose a reason for hiding this comment

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

How about something like "Example code to create a variety of plots"?

+++
.. link-button:: sphx_glr_generated_gallery
:type: ref
:text: Gallery
:classes: btn-outline-primary btn-block
---
Find out what has recently been added to Iris, or soon will be.
Copy link
Member

@rcomer rcomer Sep 28, 2020

Choose a reason for hiding this comment

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

Not sure about the "soon will be", as this won't make sense for the released docs. Also this is currently pointing to a list of all the whatsnews. Should it just be the whatsnew for the current version? If intended to point to all versions, maybe "Find out what has changed in Iris" would be more all-encompassing.

Copy link
Contributor

@trexfeathers trexfeathers Sep 28, 2020

Choose a reason for hiding this comment

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

To be fair, all of it has been recently added to Iris, but only some of it has been released so far.

Copy link
Member

@rcomer rcomer Sep 28, 2020

Choose a reason for hiding this comment

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

In fact, some things have be removed from Iris....

Copy link
Contributor Author

@tkknight tkknight Sep 28, 2020

Choose a reason for hiding this comment

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

how about:

"Find out what has recently changed in Iris."

Copy link
Contributor

@trexfeathers trexfeathers Sep 28, 2020

Choose a reason for hiding this comment

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

"Find out what has recently changed in Iris."

I'm in favour of this

+++
.. link-button:: iris_whatsnew
:type: ref
:text: What's new
Copy link
Member

@rcomer rcomer Sep 28, 2020

Choose a reason for hiding this comment

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

Capital N for consistency with the other buttons?

:classes: btn-outline-primary btn-block
---
Learn how to use Iris.
+++
.. link-button:: user_guide_index
:type: ref
:text: User Guide
:classes: btn-outline-primary btn-block
---
Documentation for the Iris Application Programming Interface.
Copy link
Member

@rcomer rcomer Sep 28, 2020

Choose a reason for hiding this comment

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

I'm not sure whether API is a familiar term for a lot of our target user-base. Maybe something like "Browse full Iris functionality by module"?

+++
.. link-button:: Iris
:type: ref
:text: Iris API
:classes: btn-outline-primary btn-block
---
As a developer you can contribute to Iris.
+++
.. link-button:: development_where_to_start
:type: ref
:text: Getting Involved
:classes: btn-outline-primary btn-block


.. toctree::
:maxdepth: 1
:caption: Getting started
:hidden:

installing
generated/gallery/index
Expand All @@ -58,6 +102,7 @@ Iris is part of SciTools, for more information see https://scitools.org.uk/.
:maxdepth: 1
:caption: User Guide
:name: userguide_index
:hidden:

userguide/index
userguide/iris_cubes
Expand All @@ -81,20 +126,22 @@ Iris is part of SciTools, for more information see https://scitools.org.uk/.
:maxdepth: 1
:caption: Developers Guide
:name: development_index
:hidden:

developers_guide/contributing_getting_involved
developers_guide/gitwash/index
developers_guide/contributing_documentation
developers_guide/contributing_codebase_index
developers_guide/contributing_changes
developers_guide/release
generated/api/iris


.. toctree::
:maxdepth: 1
:caption: Reference
:hidden:

generated/api/iris
whatsnew/index
techpapers/index
copyright
2 changes: 2 additions & 0 deletions requirements/ci/py36.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,5 @@ dependencies:
- pip
- pip:
- sphinxcontrib-napoleon
- sphinx-panels

1 change: 1 addition & 0 deletions requirements/ci/py37.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,4 @@ dependencies:
- pip
- pip:
- sphinxcontrib-napoleon
- sphinx-panels
1 change: 1 addition & 0 deletions requirements/docs.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@ sphinx-copybutton
sphinx-gallery
sphinx_rtd_theme
sphinxcontrib-napoleon
sphinx-panels