diff --git a/docs/main.py b/docs/main.py index 266f53456..685b64815 100644 --- a/docs/main.py +++ b/docs/main.py @@ -20,7 +20,7 @@ @app.route("/") async def forward_to_index(request): - return response.redirect("/docs/content/index.html") + return response.redirect("/docs/index.html") mount, element = multiview() diff --git a/docs/source/exts/async_doctest.py b/docs/source/_exts/async_doctest.py similarity index 100% rename from docs/source/exts/async_doctest.py rename to docs/source/_exts/async_doctest.py diff --git a/docs/source/exts/interactive_widget.py b/docs/source/_exts/interactive_widget.py similarity index 100% rename from docs/source/exts/interactive_widget.py rename to docs/source/_exts/interactive_widget.py diff --git a/docs/source/exts/widget_example.py b/docs/source/_exts/widget_example.py similarity index 97% rename from docs/source/exts/widget_example.py rename to docs/source/_exts/widget_example.py index 078671f5c..90dae1800 100644 --- a/docs/source/exts/widget_example.py +++ b/docs/source/_exts/widget_example.py @@ -1,4 +1,3 @@ -import textwrap from pathlib import Path from sphinx.application import Sphinx @@ -112,7 +111,7 @@ def _literal_include_js_lines(name, linenos): def _string_to_nested_lines(content): - return StringList(textwrap.indent(content, " ").split("\n")) + return StringList(content.split("\n")) def setup(app: Sphinx) -> None: diff --git a/docs/source/static/css/fix-code-linenos.css b/docs/source/_static/css/fix-code-linenos.css similarity index 100% rename from docs/source/static/css/fix-code-linenos.css rename to docs/source/_static/css/fix-code-linenos.css diff --git a/docs/source/static/css/interactive-widget.css b/docs/source/_static/css/interactive-widget.css similarity index 100% rename from docs/source/static/css/interactive-widget.css rename to docs/source/_static/css/interactive-widget.css diff --git a/docs/source/static/custom_victory_chart.png b/docs/source/_static/custom_victory_chart.png similarity index 100% rename from docs/source/static/custom_victory_chart.png rename to docs/source/_static/custom_victory_chart.png diff --git a/docs/source/static/primary_secondary_buttons.png b/docs/source/_static/primary_secondary_buttons.png similarity index 100% rename from docs/source/static/primary_secondary_buttons.png rename to docs/source/_static/primary_secondary_buttons.png diff --git a/docs/source/static/victory_bar_default_chart.png b/docs/source/_static/victory_bar_default_chart.png similarity index 100% rename from docs/source/static/victory_bar_default_chart.png rename to docs/source/_static/victory_bar_default_chart.png diff --git a/docs/source/content/branding/idom-logo-black-square.svg b/docs/source/branding/idom-logo-black-square.svg similarity index 100% rename from docs/source/content/branding/idom-logo-black-square.svg rename to docs/source/branding/idom-logo-black-square.svg diff --git a/docs/source/content/branding/idom-logo-black.png b/docs/source/branding/idom-logo-black.png similarity index 100% rename from docs/source/content/branding/idom-logo-black.png rename to docs/source/branding/idom-logo-black.png diff --git a/docs/source/content/branding/idom-logo-black.svg b/docs/source/branding/idom-logo-black.svg similarity index 100% rename from docs/source/content/branding/idom-logo-black.svg rename to docs/source/branding/idom-logo-black.svg diff --git a/docs/source/content/branding/idom-logo-square.svg b/docs/source/branding/idom-logo-square.svg similarity index 100% rename from docs/source/content/branding/idom-logo-square.svg rename to docs/source/branding/idom-logo-square.svg diff --git a/docs/source/content/branding/idom-logo-white-square.svg b/docs/source/branding/idom-logo-white-square.svg similarity index 100% rename from docs/source/content/branding/idom-logo-white-square.svg rename to docs/source/branding/idom-logo-white-square.svg diff --git a/docs/source/branding/idom-logo-white.png b/docs/source/branding/idom-logo-white.png new file mode 100644 index 000000000..ecaf9de33 Binary files /dev/null and b/docs/source/branding/idom-logo-white.png differ diff --git a/docs/source/content/branding/idom-logo.png b/docs/source/branding/idom-logo.png similarity index 100% rename from docs/source/content/branding/idom-logo.png rename to docs/source/branding/idom-logo.png diff --git a/docs/source/content/branding/idom-logo.svg b/docs/source/branding/idom-logo.svg similarity index 100% rename from docs/source/content/branding/idom-logo.svg rename to docs/source/branding/idom-logo.svg diff --git a/docs/source/conf.py b/docs/source/conf.py index adab4401f..d30ee0060 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,7 +18,7 @@ sys.path.insert(0, str(here.parent.parent)) # extension path -sys.path.insert(0, str(here / "exts")) +sys.path.insert(0, str(here / "_exts")) # -- Project information ----------------------------------------------------- @@ -52,6 +52,7 @@ "widget_example", "async_doctest", "sphinx_panels", + "sphinx_copybutton", ] # Add any paths that contain templates here, relative to this directory. @@ -64,7 +65,7 @@ source_suffix = ".rst" # The master toctree document. -master_doc = "content/index" +master_doc = "index" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -95,7 +96,11 @@ # -- sphinx.ext.autodoc -- # show base classes for autodoc -autodoc_default_flags = ["show-inheritance", "inherited-members"] +autodoc_default_options = { + "show-inheritance": True, + "inherited-members": True, + "member-order": "bysource", +} # order autodoc members by their order in the source autodoc_member_order = "bysource" @@ -104,35 +109,24 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "pydata_sphinx_theme" +html_theme = "furo" +html_logo = "branding/idom-logo-white.png" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # -html_theme_options = { - "github_url": "https://github.com/idom-team/idom", - "use_edit_page_button": True, - "show_toc_level": 2, -} - -html_context = { - "github_user": "idom-team", - "github_repo": "idom", - "github_version": "main", - "doc_path": "docs/source", -} +# html_theme_options = {} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["static"] +html_static_path = ["_static"] # These paths are either relative to html_static_path # or fully qualified paths (eg. https://...) html_css_files = [ "css/interactive-widget.css", - "css/fix-code-linenos.css", ] # Custom sidebar templates, must be a dictionary that maps document names diff --git a/docs/source/content/advanced-usage/index.rst b/docs/source/content/advanced-usage/index.rst deleted file mode 100644 index c74130382..000000000 --- a/docs/source/content/advanced-usage/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -Advanced Usage -============== - -Explains the high level abstractions of IDOM like layouts, distpatchers and servers as -well as more advanced features that allow you to import existing or custom javascript -into your IDOM views. If you're just getting started check out the :ref:`User Guide` -first before you dive in here. - -.. toctree:: - :maxdepth: 1 - - core-concepts - javascript-modules - extra-features diff --git a/docs/source/content/api-reference/index.rst b/docs/source/content/api-reference/index.rst deleted file mode 100644 index 930b90920..000000000 --- a/docs/source/content/api-reference/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -API Reference -============= - -Detailed explanations of classes, functions, and protocols used by IDOM. - -.. toctree:: - :maxdepth: 1 - - package-api - specifications diff --git a/docs/source/content/user-guide/index.rst b/docs/source/content/user-guide/index.rst deleted file mode 100644 index 272d983cd..000000000 --- a/docs/source/content/user-guide/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -User Guide -========== - -This guide is intended as an introductory overview of IDOM and explains how to install -and make use of its most important features. For detailed usage and reference -documentation see the :ref:`Advanced Usage` or :ref:`API Reference` sections respectively. - -.. toctree:: - :maxdepth: 1 - - installation - getting-started - life-cycle-hooks diff --git a/docs/source/content/advanced-usage/core-concepts.rst b/docs/source/core-concepts.rst similarity index 99% rename from docs/source/content/advanced-usage/core-concepts.rst rename to docs/source/core-concepts.rst index b453440cd..90897f2aa 100644 --- a/docs/source/content/advanced-usage/core-concepts.rst +++ b/docs/source/core-concepts.rst @@ -4,10 +4,6 @@ Core Concepts This section covers core features of IDOM that are used in making interactive interfaces. -.. contents:: - :local: - :depth: 1 - Pure Elements ------------- diff --git a/docs/source/content/advanced-usage/javascript-modules.rst b/docs/source/custom-javascript.rst similarity index 89% rename from docs/source/content/advanced-usage/javascript-modules.rst rename to docs/source/custom-javascript.rst index 7ead01ede..3c6442a03 100644 --- a/docs/source/content/advanced-usage/javascript-modules.rst +++ b/docs/source/custom-javascript.rst @@ -1,15 +1,11 @@ -Javascript Modules -================== +Custom Javascript +================= .. note:: This is a recent feature of IDOM. If you have a problem following this tutorial `post an issue `__. -.. contents:: - :local: - :depth: 1 - While IDOM is a great tool for displaying HTML and responding to browser events with pure Python, there are other projects which already allow you to do this inside `Jupyter Notebooks `__ @@ -19,11 +15,7 @@ The real power of IDOM comes from its ability to seemlessly leverage the existin ecosystem of `React components `__. -So long as your library of interest is an -`ES Module `__ -you could install using -`Snowpack `__ -you can use it with IDOM +So long as your library of interest can be installed NPM_, you can use it with IDOM You can even define your own Javascript modules which use these third party Javascript packages. @@ -33,7 +25,7 @@ Installing React Components .. note:: - Be sure that you've installed `npm `__. + Be sure that you `install NPM`_ before continuing. In this example we'll be using the ubiquitous React-based UI framework `Material UI`_ which can be easily installed using the ``idom`` CLI: @@ -95,3 +87,5 @@ under construction... .. ===== .. _Material UI: https://material-ui.com/ +.. _NPM: https://www.npmjs.com +.. _install NPM: https://www.npmjs.com/get-npm diff --git a/docs/source/content/examples.rst b/docs/source/examples.rst similarity index 94% rename from docs/source/content/examples.rst rename to docs/source/examples.rst index e59cfb601..14992c802 100644 --- a/docs/source/content/examples.rst +++ b/docs/source/examples.rst @@ -1,10 +1,6 @@ Examples ======== -.. contents:: - :local: - :depth: 1 - Slideshow --------- @@ -31,7 +27,7 @@ Try typing in the text box and pressing 'Enter' 📋 The Game Snake -------------- -Click to start playing and use WASD to move 🎮 +Click to start playing and use the arrow keys to move 🎮 Slow internet may cause inconsistent frame pacing 😅 diff --git a/docs/source/examples/snake_game.py b/docs/source/examples/snake_game.py index f7739383e..bfe26ab37 100644 --- a/docs/source/examples/snake_game.py +++ b/docs/source/examples/snake_game.py @@ -34,16 +34,16 @@ def GameView(): class Direction(enum.Enum): - w = (0, -1) - a = (-1, 0) - s = (0, 1) - d = (1, 0) + ArrowUp = (0, -1) + ArrowLeft = (-1, 0) + ArrowDown = (0, 1) + ArrowRight = (1, 0) @idom.element def GameLoop(grid_size, block_scale, set_game_state): # we `use_ref` here to capture the latest direction press without any delay - direction = idom.hooks.use_ref(Direction.d.value) + direction = idom.hooks.use_ref(Direction.ArrowRight.value) snake, set_snake = idom.hooks.use_state([(grid_size // 2 - 1, grid_size // 2 - 1)]) food, set_food = use_snake_food(grid_size, snake) diff --git a/docs/source/content/advanced-usage/extra-features.rst b/docs/source/extra-features.rst similarity index 98% rename from docs/source/content/advanced-usage/extra-features.rst rename to docs/source/extra-features.rst index f67b0bde9..953f76752 100644 --- a/docs/source/content/advanced-usage/extra-features.rst +++ b/docs/source/extra-features.rst @@ -3,10 +3,6 @@ Extra Features Optionally installable features of IDOM. -.. contents:: - :local: - :depth: 1 - To install a **stable** set of features for IDOM simply run. .. code-block:: diff --git a/docs/source/content/user-guide/getting-started.rst b/docs/source/getting-started.rst similarity index 100% rename from docs/source/content/user-guide/getting-started.rst rename to docs/source/getting-started.rst diff --git a/docs/source/content/index.rst b/docs/source/index.rst similarity index 80% rename from docs/source/content/index.rst rename to docs/source/index.rst index cf1a0a354..a80c7d929 100644 --- a/docs/source/content/index.rst +++ b/docs/source/index.rst @@ -1,19 +1,28 @@ -IDOM |release| -============== - -.. image:: branding/idom-logo.png - :height: 250px +IDOM +==== Libraries for defining and controlling interactive webpages with Python 3.7 and above. .. toctree:: - :maxdepth: 1 - - user-guide/index + :hidden: + :caption: User Guide + + installation + getting-started + life-cycle-hooks + core-concepts + custom-javascript examples - advanced-usage/index - api-reference/index + +.. toctree:: + :hidden: + :caption: Reference + + GitHub + package-api + specifications + extra-features Early Days diff --git a/docs/source/content/user-guide/installation.rst b/docs/source/installation.rst similarity index 98% rename from docs/source/content/user-guide/installation.rst rename to docs/source/installation.rst index be82e4480..9acc28a58 100644 --- a/docs/source/content/user-guide/installation.rst +++ b/docs/source/installation.rst @@ -21,7 +21,7 @@ Installation idom install some-js-package - For more info see the :ref:`Javascript Modules` section. + For more info see the :ref:`Custom Javascript` section. * - Extra Features diff --git a/docs/source/content/user-guide/life-cycle-hooks.rst b/docs/source/life-cycle-hooks.rst similarity index 99% rename from docs/source/content/user-guide/life-cycle-hooks.rst rename to docs/source/life-cycle-hooks.rst index 903b91136..fa39368c1 100644 --- a/docs/source/content/user-guide/life-cycle-hooks.rst +++ b/docs/source/life-cycle-hooks.rst @@ -13,10 +13,6 @@ cases the :ref:`Basic Hooks` should be enough, however the remaining `In the future `_ they will be added, but if you have a particular need for a missing hook post an issue. -.. contents:: - :local: - :depth: 2 - Basic Hooks =========== diff --git a/docs/source/content/api-reference/mimetype.json b/docs/source/mimetype.json similarity index 100% rename from docs/source/content/api-reference/mimetype.json rename to docs/source/mimetype.json diff --git a/docs/source/content/api-reference/package-api.rst b/docs/source/package-api.rst similarity index 96% rename from docs/source/content/api-reference/package-api.rst rename to docs/source/package-api.rst index 97a30b8a5..5f8337279 100644 --- a/docs/source/content/api-reference/package-api.rst +++ b/docs/source/package-api.rst @@ -1,10 +1,6 @@ Package API =========== -.. contents:: - :local: - :depth: 1 - .. module:: idom diff --git a/docs/source/content/api-reference/specifications.rst b/docs/source/specifications.rst similarity index 99% rename from docs/source/content/api-reference/specifications.rst rename to docs/source/specifications.rst index f3d523b4a..ed71cb8a9 100644 --- a/docs/source/content/api-reference/specifications.rst +++ b/docs/source/specifications.rst @@ -10,10 +10,6 @@ created by `Nteract `_ and which was built into for VDOM is fairly well established, it should not be relied until it's been fully adopted by the aforementioned organizations. -.. contents:: - :local: - :depth: 1 - VDOM Mimetype ------------- diff --git a/requirements/docs.txt b/requirements/docs.txt index 14984aa11..2368cbc6d 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -1,5 +1,6 @@ -sphinx ==2.2.0 +sphinx ==3.2.1 sphinx-autodoc-typehints ==1.7.0 -pydata-sphinx-theme ==0.4.1 +furo ==2020.10.13b12 sphinx-panels ==0.5.0 setuptools_scm +sphinx-copybutton ==0.3.0