From 5764aaf5ddbd0d84d9ae4033b3ed4636a8f39b36 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 5 Jun 2020 15:39:15 -0700 Subject: [PATCH] replacing index.html hard-code with an rST page --- .circleci/config.yml | 7 +- .travis.yml | 4 +- docs/doc-requirements.txt | 1 + docs/source/_static/custom.css | 25 +++ docs/source/_templates/index.html | 87 ----------- docs/source/_templates/layout.html | 4 - docs/source/_templates/navbar.html | 45 ------ docs/source/_templates/sidebartoc.html | 1 - docs/source/conf.py | 15 +- docs/source/contents.rst | 81 ---------- docs/source/index.rst | 201 +++++++++++++++++++++++++ 11 files changed, 243 insertions(+), 228 deletions(-) delete mode 100644 docs/source/_templates/index.html delete mode 100644 docs/source/_templates/layout.html delete mode 100644 docs/source/_templates/navbar.html delete mode 100644 docs/source/_templates/sidebartoc.html delete mode 100644 docs/source/contents.rst create mode 100644 docs/source/index.rst diff --git a/.circleci/config.yml b/.circleci/config.yml index e56859c1a..bc4bf75cb 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -12,8 +12,7 @@ jobs: - cache-pip - run: pip install --user -e . - run: pip install --user -r docs/doc-requirements.txt - - run: pip install --user sphinx_rtd_theme - + # Cache some files for a speedup in subsequent builds - save_cache: key: cache-pip @@ -25,7 +24,7 @@ jobs: command: | cd docs make html - + # Tell Circle to store the documentation output in a folder that we can access later - store_artifacts: path: docs/build/html/ @@ -36,4 +35,4 @@ workflows: version: 2 default: jobs: - - docs \ No newline at end of file + - docs diff --git a/.travis.yml b/.travis.yml index 21d152f38..6551be719 100644 --- a/.travis.yml +++ b/.travis.yml @@ -8,7 +8,7 @@ jobs: - stage: test-docs install: - pip install --upgrade pip sphinx - - pip install pydata_sphinx_theme recommonmark sphinx-intl + - pip install -r docs/doc-requirements.txt script: # Test build of HTML docs and English translation templates - make -C docs html @@ -17,7 +17,7 @@ jobs: - stage: push-tx install: - pip install --upgrade pip sphinx - - pip install pydata_sphinx_theme recommonmark sphinx-intl + - pip install -r docs/doc-requirements.txt script: - cd docs # Rebuild HTML again to test for merge problems diff --git a/docs/doc-requirements.txt b/docs/doc-requirements.txt index 910ddd4ef..e8de39a9e 100644 --- a/docs/doc-requirements.txt +++ b/docs/doc-requirements.txt @@ -3,3 +3,4 @@ sphinx-intl recommonmark==0.4.0 nbsphinx pydata-sphinx-theme +sphinx-panels diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css index 5986288fd..abfd7b9b5 100644 --- a/docs/source/_static/custom.css +++ b/docs/source/_static/custom.css @@ -20,3 +20,28 @@ p.first.admonition-title { color: #ffffff; } + +/* Front page table styling */ + +.front-page-table td > p { + margin-bottom: 0em; +} + +.front-page-table td > p:last-child { + font-style: italic; +} + +.front-page-table a.reference { + font-size: 1.3em; +} + +.front-page-table.table td, .front-page-table.table th { + border: none; + padding-top: .3em; + padding-bottom: .3em; +} + +div.card ul.simple { + list-style: none; + padding-left: 1em; +} diff --git a/docs/source/_templates/index.html b/docs/source/_templates/index.html deleted file mode 100644 index b56da1b47..000000000 --- a/docs/source/_templates/index.html +++ /dev/null @@ -1,87 +0,0 @@ -{% extends "layout.html" %} -{% set title = _('Overview') %} -{% block body %} -

{{ _('Welcome') }}

- - -

{%trans%}Start Here{%endtrans%}

- - - - - - - - -
-

{%trans%}Jupyter Notebook Quickstart{%endtrans%}
- {%trans%}Try the notebook{%endtrans%}

-

{%trans%}Architecture{%endtrans%}
- {%trans%}What is Jupyter?{%endtrans%}

-

{%trans%}Narratives and Use Cases{%endtrans%}
- {%trans%}Narratives of common deployment scenarios{%endtrans%}

-

{%trans%}IPython{%endtrans%}
- {%trans%}An interactive Python kernel and REPL{%endtrans%}

-

{%trans%}Installation, Configuration, and Usage{%endtrans%}
- {%trans%}Documentation for users{%endtrans%}

- 		-

{%trans%}Community{%endtrans%}
- {%trans%}Sustainability and growth{%endtrans%}

-

{%trans%}Contributor Guides{%endtrans%}
- {%trans%}How to contribute to the projects{%endtrans%}

-

{%trans%}Release Notes{%endtrans%}
- {%trans%}New features, upgrades, deprecation notes, and bug fixes{%endtrans%}

-

{%trans%}Reference{%endtrans%}
- {%trans%}APIs{%endtrans%}

-

{%trans%}Contents{%endtrans%}
- {%trans%}Full table of contents{%endtrans%}

-
- -

{%trans%}Project Documentation{%endtrans%}

- - - -
-

Jupyter User Interfaces

- {%trans%}Jupyter Notebook{%endtrans%}
- {%trans%}Jupyter console{%endtrans%}
- {%trans%}Qt console{%endtrans%}

-

JupyterHub

- {%trans%}JupyterHub{%endtrans%}
- {%trans%}configurable HTTP proxy{%endtrans%}
- {%trans%}dockerspawner{%endtrans%}
- {%trans%}ldapauthenticator{%endtrans%}
- {%trans%}oauthenticator{%endtrans%}
- {%trans%}sudospawner{%endtrans%}

-

Education

- {%trans%}nbgrader{%endtrans%}

-

Conversion and Formatting

- {%trans%}nbconvert{%endtrans%}
- {%trans%}nbformat{%endtrans%}

-

Kernels

- {%trans%}IPython{%endtrans%}
- {%trans%}IRkernel{%endtrans%}
- {%trans%}IJulia{%endtrans%}
- {%trans%}Community maintained kernels{%endtrans%}


- 		-

IPython

- {%trans%}IPython{%endtrans%}
- {%trans%}ipykernel{%endtrans%}
- {%trans%}ipyparallel{%endtrans%}

-

Architecture

- {%trans%}jupyter_client{%endtrans%}
- {%trans%}jupyter_core{%endtrans%}

-

Deployment

- {%trans%}docker-stacks{%endtrans%}
- {%trans%}ipywidgets{%endtrans%}
- {%trans%}jupyter-drive{%endtrans%}
- {%trans%}jupyter-sphinx-theme{%endtrans%}
- {%trans%}kernel_gateway{%endtrans%}
- {%trans%}nbviewer{%endtrans%}
- {%trans%}tmpnb{%endtrans%}
- {%trans%}traitlets{%endtrans%}

-

JupyterLab

- {%trans%}jupyter-js-services{%endtrans%}
-
- -{% endblock %} diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html deleted file mode 100644 index 04cdcb444..000000000 --- a/docs/source/_templates/layout.html +++ /dev/null @@ -1,4 +0,0 @@ -{% extends "!layout.html" %} - -{# Custom CSS overrides #} -{% set bootswatch_css_custom = ['_static/custom.css'] %} \ No newline at end of file diff --git a/docs/source/_templates/navbar.html b/docs/source/_templates/navbar.html deleted file mode 100644 index 981043269..000000000 --- a/docs/source/_templates/navbar.html +++ /dev/null @@ -1,45 +0,0 @@ -
-
-
- - - - {%- block sidebarlogo %} - {%- if logo %}{%- endif %} - {%- endblock %} - {% if theme_navbar_title -%}{{ theme_navbar_title|e }}{%- else -%}{{ project|e }}{%- endif -%} - - {{ version|e }} -
- -
-
    - {% if theme_navbar_links %} - {%- for link in theme_navbar_links %} -
  • {{ link[0] }}
    • - {%- endfor %} - {% endif %} - {% block navbarextra %} - {% endblock %} - {% if theme_source_link_position == "nav" %} - - {% endif %} -
- - {% block navbarsearch %} - {% include "navbarsearchbox.html" %} - {% endblock %} - {% if theme_navbar_sidebarrel %} - {% block sidebarrel %} -
    - {% include "relations.html" %} -
- {% endblock %} - {% endif %} -
-
-
\ No newline at end of file diff --git a/docs/source/_templates/sidebartoc.html b/docs/source/_templates/sidebartoc.html deleted file mode 100644 index b64bec6bb..000000000 --- a/docs/source/_templates/sidebartoc.html +++ /dev/null @@ -1 +0,0 @@ -{{ toctree(maxdepth=2, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }} \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index a3b994bf5..72156c3b3 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -29,9 +29,12 @@ 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.graphviz', # Add the graphviz extension - 'recommonmark' + 'recommonmark', + 'sphinx_panels' ] +panels_add_boostrap_css = False + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -43,7 +46,7 @@ #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'contents' +master_doc = 'index' # General information about the project. project = 'Jupyter Documentation' @@ -92,7 +95,7 @@ # Additional templates that should be rendered to pages, maps page names to # template names. -html_additional_pages = {'index': 'index.html'} +html_additional_pages = {} # Output file base name for HTML help builder. htmlhelp_basename = 'Jupyter' @@ -168,4 +171,8 @@ # -- Translation ---------------------------------------------------------- gettext_uuid = True -locale_dirs = ['locale/'] \ No newline at end of file +locale_dirs = ['locale/'] + + +def setup(app): + app.add_css_file("custom.css") diff --git a/docs/source/contents.rst b/docs/source/contents.rst deleted file mode 100644 index 4564144d7..000000000 --- a/docs/source/contents.rst +++ /dev/null @@ -1,81 +0,0 @@ -=========================== -Project Jupyter and IPython -=========================== - -**Table of Contents** - -.. _user-docs: - -.. toctree:: - :maxdepth: 2 - - content-quickstart - -.. _tech-overview: - -.. toctree:: - :maxdepth: 1 - - architecture/content-architecture.rst - -.. _about-docs: - -.. toctree:: - :maxdepth: 2 - - use-cases/content-user.rst - -.. _about-ipython: - -.. toctree:: - :maxdepth: 2 - - ipython/content-ipython.rst - -.. _jupyter-subprojects: - -.. toctree:: - :maxdepth: 2 - - projects/content-projects - -.. toctree:: - :maxdepth: 2 - - community/content-community - -.. _dev-docs: - -.. toctree:: - :maxdepth: 2 - - contributor/content-contributor - -.. toctree:: - :maxdepth: 2 - - reference/content-reference - - - -Indices and tables -================== - -- :ref:`genindex` -- :ref:`glossary` -- :ref:`search` - - -**Resources:** - -.. csv-table:: - :header: "Site", "Description" - :widths: 18, 35 - - `Jupyter website `_, Keep up to date on Jupyter - `IPython website `_, Learn more about IPython - `jupyter/help repo `_, Start here for help and support questions - `Jupyter mailing list `_, General discussion of Jupyter's use - `Jupyter in Education group `_, Discussion of Jupyter's use in education - `NumFocus `_, "Promotes world-class, innovative, open source scientific software" - `Donate to Project Jupyter `_, Please contribute to open science collaboration and sustainability diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..da6e598c5 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,201 @@ +============================= +Jupyter Project Documentation +============================= + +**Welcome to the Jupyter Project documentation**. This website acts as "meta" documentation +for the Jupyter ecosystem. It has a collection of resources to navigate the tools +and communities in this ecosystem, and to help you get started. + + +Start Here +========== + +.. list-table:: + :class: front_page_table + + * - `Jupyter Notebook Quickstart `_ + + Try the notebook + + - `Community `_ + + Sustainability and growth + + * - `Architecture `_ + + What is Jupyter? + + - `Contributor Guides `_ + + How to contribute to the projects + + * - `Narratives and Use Cases `_ + + Narratives of common deployment scenarios + + - `Release Notes `_ + + New features, upgrades, deprecation notes, and bug fixes + + * - `IPython `_ + + An interactive Python kernel and REPL + + - `Reference `_ + + APIs + + * - `Installation, Configuration, and Usage `_ + + Documentation for users + + - + +Sub-project documentation +========================= + +.. panels:: + + Jupyter User Interfaces + ^^^^^^ + * `Jupyter Notebook `_ + * `Jupyter console `_ + * `Qt console `_ + + --- + JupyterHub + ^^^^^^ + * `JupyterHub `_ + * `configurable HTTP proxy `_ + * `dockerspawner `_ + * `ldapauthenticator `_ + * `oauthenticator `_ + * `sudospawner `_ + + --- + Education + ^^^^^^ + * `nbgrader `_ + + --- + Conversion and Formatting + ^^^^^^ + * `nbconvert `_ + * `nbformat `_ + + --- + Kernels + ^^^^^^ + * `IPython `_ + * `IRkernel `_ + * `IJulia `_ + * `Community maintained kernels `_ + + --- + IPython + ^^^^^^ + * `IPython `_ + * `ipykernel `_ + * `ipyparallel `_ + + --- + Architecture + ^^^^^^ + * `jupyter_client `_ + * `jupyter_core `_ + + --- + Deployment + ^^^^^^ + * `docker-stacks `_ + * `jupyter-sphinx-theme `_ + * `kernel_gateway `_ + * `nbviewer `_ + * `tmpnb `_ + * `traitlets `_ + + --- + JupyterLab + ^^^^^^ + * `JupyterLab `_ + * `ipywidgets `_ + + +Table of Contents +================= + +.. _user-docs: + +.. toctree:: + :maxdepth: 2 + + content-quickstart + +.. _tech-overview: + +.. toctree:: + :maxdepth: 1 + + architecture/content-architecture.rst + +.. _about-docs: + +.. toctree:: + :maxdepth: 2 + + use-cases/content-user.rst + +.. _about-ipython: + +.. toctree:: + :maxdepth: 2 + + ipython/content-ipython.rst + +.. _jupyter-subprojects: + +.. toctree:: + :maxdepth: 2 + + projects/content-projects + +.. toctree:: + :maxdepth: 2 + + community/content-community + +.. _dev-docs: + +.. toctree:: + :maxdepth: 2 + + contributor/content-contributor + +.. toctree:: + :maxdepth: 2 + + reference/content-reference + + + +Indices and tables +================== + +- :ref:`genindex` +- :ref:`glossary` +- :ref:`search` + + +**Resources:** + +.. csv-table:: + :header: "Site", "Description" + :widths: 18, 35 + + `Jupyter website `_, Keep up to date on Jupyter + `IPython website `_, Learn more about IPython + `jupyter/help repo `_, Start here for help and support questions + `Jupyter mailing list `_, General discussion of Jupyter's use + `Jupyter in Education group `_, Discussion of Jupyter's use in education + `NumFocus `_, "Promotes world-class, innovative, open source scientific software" + `Donate to Project Jupyter `_, Please contribute to open science collaboration and sustainability