Documentation infrastructure. (#262)

* Initial setup.

This does a few things:

- Adds some placeholders following the Diátaxis framework (https://diataxis.fr)
- Sets up Sphinx with MyST parser for Markdown in addition to rST.
- Uses the well-known PyData Sphinx theme.
- Moves some already existing Markdown files into the docs directory.
- Sets up the initial doc review GitHub action to auto-deploy to GitHub pages.

* Activate conda env.

* Remove custom action.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Make the dir.

* Push directly

* Add readthedocs config.

* Disable GitHub pages deployment for now.

* Add release and latest workflows as well.

* Make clear that this is work in progress.

* Made docs merge ready, added What is PyScript section with example.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Replace `on:tags:` with `on:create:`

The existing trigger is apparently not in the GHA spec

* Pretty format YAML

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* add s3 sync and permissions

* Leave status message in PR.

* Redirect from docs.pyscript.net/ to docs.pyscript.net/latest/

* Delete latest directory before deployment.

* Update review and release workflows, too.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Allow access to S3 for review and release doc workflow.

* Fix name of workflow.

* Bump up Python version.

* Because YAML.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Revert move to 3.10.

* Fix sitemap.

* Remove status settgin from release and latest build.

* Comment out cleanup.

* Add write permissions for statuses.

* More permissions?

* Fix artifact name.

* Use appropriate concurrency.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* .zip not needed

* Align name of workflows with CI workflows.

* Add checks permission.

* Set a notice instead.

* Move to sphinx-design.

* Add sphinx-autobuild.

* Use frontmatter more.

* Add section for mdformat but disable it for now.

See https://github.com/executablebooks/mdformat-myst/pull/9 for more details.

* Fix fencing.

* Actually using html renderer.

* Revert moving governance files.

* Use full URLs for governance docs.

* Added warning.

* Fix copyright and author.

* Another minor fix.

* Use GitHub Action summary instead of notice.

* Fix variable name.

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Matt Kramer <mkramer@anaconda.com>
Co-authored-by: ximena9201 <ximenandrea.ro@gmail.com>

docs/Makefile

@@ -0,0 +1,45 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+CONDA_ENV     ?= _env
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+env := $(CONDA_ENV)
+conda_run := conda run -p $(env)
+
+setup:
+	@if [ -z "$${CONDA_SHLVL:+x}" ]; then echo "Conda is not installed." && exit 1; fi
+	$(CONDA_EXE) env $(shell [ -d $(env) ] && echo update || echo create) -p $(env) --file environment.yml
+
+clean:
+	rm -rf $(BUILDDIR)
+
+clean-all: clean
+	rm -rf $(env) *.egg-info
+
+shell:
+	@export CONDA_ENV_PROMPT='<{name}>'
+	@echo 'conda activate $(env)'
+
+htmlserve:
+	python -m http.server -d "$(BUILDDIR)/html/"
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+.PHONY: help Makefile setup clean clean-all shell
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,16 @@
+# PyScript documentation
+
+Welcome to the PyScript documentation directory, where you can find
+and contribute to discussions around PyScript and related topics.
+
+## Getting started
+
+Before you start contributing to the documentation, it's worthwhile to
+take a look at the general contributing guidelines for the PyScript project.
+
+### Setup
+
+The `docs` directory in the pyscript repository contains a
+[Sphinx](https://www.sphinx-doc.org/) documentation project. Sphinx is a system
+that takes plaintext files containing documentation written in Markdown, along with
+and static files like templates and themes, to build the static end result.

docs/_static/examples/what-is-pyscript.html

@@ -0,0 +1,44 @@
+<html>
+    <head>
+      <link rel="stylesheet" href="https://pyscript.net/alpha/pyscript.css" />
+      <script defer src="https://pyscript.net/alpha/pyscript.js"></script>
+      <style>
+        .pulse {
+            animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+        }
+
+        @keyframes pulse {
+          0%, 100% {
+            opacity: 1;
+          }
+          50% {
+            opacity: .2;
+          }
+        }
+      </style>
+      <py-env>
+        - numpy
+        - matplotlib
+      </py-env>
+    </head>
+
+  <body>
+    <h1>Let's plot random numbers</h1>
+    <div id="plot">
+      <div class="pulse" >
+        <p style='font-family: monospace sans-serif;'><big><big><big><big>&#10096;py&#10097;</big></big></big></big></p>
+      </div>
+    </div>
+    <py-script>
+import matplotlib.pyplot as plt
+import numpy as np
+
+x = np.random.randn(1000)
+y = np.random.randn(1000)
+
+fig, ax = plt.subplots()
+ax.scatter(x, y)
+pyscript.write('plot', fig)
+    </py-script>
+  </body>
+</html>

docs/_static/redirect.html

@@ -0,0 +1 @@
+<html><head><meta http-equiv="refresh" content="0; URL='/latest/'" /></head><body></body></html>

docs/concepts/governance/maintainers.md

@@ -0,0 +1 @@
+../../../MAINTAINERS.md

docs/concepts/governance/policy.md

@@ -0,0 +1 @@
+../../../GOVERNANCE.md

docs/concepts/index.md

@@ -0,0 +1,12 @@
+# Concepts
+
+This section contains various topics that are higher-level and useful to know.
+
+```{toctree}
+---
+maxdepth: 2
+glob:
+---
+what-is-pyscript
+governance/*
+```

docs/concepts/what-is-pyscript.md

@@ -0,0 +1,32 @@
+# What is PyScript?
+
+The PyScript library provides HTML tags for embedding and executing Python code in your browser. PyScript is built using [Pyodide](https://pyodide.org/en/stable/), the WebAssembly port of CPython, which is compiled using [Emscripten](https://emscripten.org/).
+
+PyScript turns the browser into a code deployment tool that anyone can learn to use.
+
+## Example
+
+In this example, we are using the `<py-script>` HTML tag to generate a Matplotlib figure and display it as an image.
+Click **Preview** to see the rendered HTML.
+
+To try it in your browser, copy the HTML source to a new HTML file and double-click it to open.
+
+
+::::{tab-set}
+:::{tab-item} HTML Source
+
+```{literalinclude} ../_static/examples/what-is-pyscript.html
+---
+linenos:
+```
+
+:::
+
+:::{tab-item} Preview
+
+```{raw} html
+<iframe height="600px" width="100%" scrolling="auto" frameborder="0" src="../_static/examples/what-is-pyscript.html"></iframe>
+```
+
+:::
+::::

docs/conf.py

@@ -0,0 +1,102 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+import os
+
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "PyScript"
+copyright = "(c) 2022, Anaconda, Inc."
+author = "Anaconda, Inc."
+language = "en"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "sphinx_togglebutton",
+    "sphinx_sitemap",
+    "sphinxemoji.sphinxemoji",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "_env", "README.md"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# 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_logo = "_static/images/avatar.jpg"
+
+# 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_css_files = ["styles/custom.css"]
+
+html_baseurl = os.environ.get("SPHINX_HTML_BASE_URL", "http://127.0.0.1:8000/")
+sitemap_locales = [None]
+sitemap_url_scheme = "{link}"
+
+html_extra_path = ["robots.txt"]
+
+html_theme_options = {
+    "github_url": "https://github.com/pyscript/pyscript",
+    "twitter_url": "https://twitter.com/pyscript_dev",
+    "icon_links_label": "Quick Links",
+    # "google_analytics_id": "G-XXXXXXXXXX",
+    "use_edit_page_button": True,
+    "show_nav_level": 2,
+    "external_links": [
+        # {"name": "GitHub repo", "url": "https://github.com/pyscript/pyscript"},
+    ],
+}
+
+html_context = {
+    "default_mode": "dark",
+    "pygment_light_style": "tango",
+    "pygment_dark_style": "native",
+    "github_user": "pyscript",
+    "github_repo": "pyscript",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "deflist",
+    "html_admonition",
+    "html_image",
+    "colon_fence",
+    "smartquotes",
+    "replacements",
+]

docs/environment.yml

@@ -0,0 +1,16 @@
+channels:
+-   conda-forge
+-   defaults
+dependencies:
+-   python=3.9
+-   pip=20.2.2
+-   Sphinx=4.5.0
+-   myst-parser=0.17.2
+-   pydata-sphinx-theme
+-   sphinx-copybutton
+-   sphinx-design
+-   sphinx-togglebutton
+-   pip:
+    -   sphinxemoji
+    -   sphinx-sitemap
+    -   sphinx-autobuild

docs/howtos/index.md

@@ -0,0 +1,18 @@
+# How-to guides
+
+Welcome to the how-to documentation section for PyScript. If you've already
+gained some experience with PyScript before and just need practical guides
+to get your ideas realized, you can learn step by step how to use PyScript here.
+
+```{note}
+Please head over to the [tutorials](../tutorials/index.md) section if you're only getting started.
+```
+
+```{toctree}
+---
+maxdepth: 2
+glob:
+caption: 'Contents:'
+---
+*
+```

docs/index.md

@@ -0,0 +1,54 @@
+# PyScript
+
+```{warning}
+Please note, this documentation is just a placeholder and **should not be used
+in reference material**. Thank you!
+```
+
+Welcome to the PyScript documentation!
+
+PyScript provides a way for you to run Python code directly in your browser, giving
+anyone the ability to program without infrastructure barriers. Add an interactive
+Python REPL directly to your website, share an interactive dashboard with a colleague
+as an HTML file, or create a client-side Python-powered web application. This documentation
+will show you how.
+
+::::{grid} 2
+:gutter: 3
+
+:::{grid-item-card} [Tutorials](tutorials/index.md)
+
+Just getting started with PyScript?
+
+Check out our [getting started guide](tutorials/getting-started.md)!
+:::
+:::{grid-item-card} [How-to guides](howtos/index.md)
+
+**Coming soon!**
+
+:::
+:::{grid-item-card} [Concepts](concepts/index.md)
+
+[What is PyScript?](concepts/what-is-pyscript.md)
+
+:::
+:::{grid-item-card} [Reference](reference/index.md)
+
+**Coming soon!**
+
+:::{toctree}
+:maxdepth: 1
+
+:::
+::::
+
+```{toctree}
+---
+maxdepth: 1
+hidden:
+---
+tutorials/index
+howtos/index
+concepts/index
+reference/index
+```

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/reference/index.md

@@ -0,0 +1,4 @@
+# Reference
+
+This reference section will have manually documented or fully
+automated code documentation. **Coming soon!**

docs/robots.txt

@@ -0,0 +1,5 @@
+User-agent: *
+Disallow: /review/
+
+Sitemap: https://docs.pyscript.net/sitemap.xml
+Host: docs.pyscript.net

docs/tutorials/deployment.md

@@ -0,0 +1,3 @@
+# Deployment
+
+**Coming soon!**

docs/tutorials/getting-started.md

@@ -0,0 +1,209 @@
+# Getting started with PyScript
+
+This page will guide you through getting started with PyScript.
+
+## Development setup
+
+PyScript does not require any development environment other
+than a web browser. We recommend using [Chrome](https://www.google.com/chrome/).
+
+If you're using [VSCode](https://code.visualstudio.com/), the
+[Live Server extension](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer)
+can be used to reload the page as you edit the HTML file.
+
+## Installation
+
+There is no installation required. In this document, we'll use
+the PyScript assets served on https://pyscript.net.
+
+If you want to download the source and build it yourself, follow
+the instructions in the README.md file.
+
+## Your first PyScript HTML file
+
+Here's a "Hello, world!" example using PyScript.
+
+Using your favorite editor, create a new file called `hello.html` in
+the same directory as your PyScript, JavaScript, and CSS files with the
+following content, and open the file in your web browser. You can typically
+open an HTML by double-clicking it in your file explorer.
+
+```html
+<html>
+  <head>
+    <link rel="stylesheet" href="https://pyscript.net/alpha/pyscript.css" />
+    <script defer src="https://pyscript.net/alpha/pyscript.js"></script>
+  </head>
+  <body> <py-script> print('Hello, World!') </py-script> </body>
+</html>
+```
+
+Notice the use of the `<py-script>` tag in the HTML body. This
+is where you'll write your Python code. In the following sections, we'll
+introduce the eight tags provided by PyScript.
+
+## The py-script tag
+
+The `<py-script>` tag lets you execute multi-line Python scripts and
+print back onto the page. For example, we can compute π.
+
+```html
+<html>
+  <head>
+    <link rel="stylesheet" href="https://pyscript.net/alpha/pyscript.css" />
+    <script defer src="https://pyscript.net/alpha/pyscript.js"></script>
+  </head>
+  <body>
+      <py-script>
+print("Let's compute π:")
+def compute_pi(n):
+    pi = 2
+    for i in range(1,n):
+        pi *= 4 * i ** 2 / (4 * i ** 2 - 1)
+    return pi
+
+pi = compute_pi(100000)
+s = f"π is approximately {pi:.3f}"
+print(s)
+      </py-script>
+  </body>
+</html>
+```
+
+### Writing into labeled elements
+
+In the example above, we had a single `<py-script>` tag and it printed
+one or more lines onto the page in order. Within the `<py-script>`, you
+have access to the `pyscript` module, which provides a `.write()` method
+to send strings into labeled elements on the page.
+
+For example, we'll add some style elements and provide place holders for
+the `<py-script>` tag write to.
+
+```html
+<html>
+    <head>
+      <link rel="stylesheet" href="https://pyscript.net/alpha/pyscript.css" />
+      <script defer src="https://pyscript.net/alpha/pyscript.js"></script>
+      <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous">
+    </head>
+
+  <body>
+    <b><p>Today is <u><label id='today'></label></u></p></b>
+    <br>
+    <div id="pi" class="alert alert-primary"></div>
+    <py-script>
+import datetime as dt
+pyscript.write('today', dt.date.today().strftime('%A %B %d, %Y'))
+
+def compute_pi(n):
+    pi = 2
+    for i in range(1,n):
+        pi *= 4 * i ** 2 / (4 * i ** 2 - 1)
+    return pi
+
+pi = compute_pi(100000)
+pyscript.write('pi', f'π is approximately {pi:.3f}')
+    </py-script>
+  </body>
+</html>
+```
+
+## Packages and modules
+
+In addition to the [Python Standard Library](https://docs.python.org/3/library/) and
+the `pyscript` module, many 3rd-party OSS packages will work out-of-the-box with PyScript.
+
+In order to use them, you will need to declare the dependencies using the `<py-env>` in the
+HTML head. You can also link to `.whl` files directly on disk like in our [toga example](https://github.com/pyscript/pyscript/blob/main/pyscriptjs/examples/toga/freedom.html).
+
+```
+<py-env>
+- './static/wheels/travertino-0.1.3-py3-none-any.whl'
+</py-env>
+```
+
+If your `.whl` is not a pure Python wheel, then open a PR or issue with [pyodide](https://github.com/pyodide/pyodide) to get it added [here](https://github.com/pyodide/pyodide/tree/main/packages).
+If there's enough popular demand, the pyodide team will likely work on supporting your package. Regardless, things will likely move faster if you make the PR and consult with the team to get unblocked.
+
+For example, NumPy and Matplotlib are available. Notice here we're using `<py-script output="plot">`
+as a shortcut, which takes the expression on the last line of the script and runs `pyscript.write('plot', fig)`.
+
+```html
+<html>
+    <head>
+      <link rel="stylesheet" href="https://pyscript.net/alpha/pyscript.css" />
+      <script defer src="https://pyscript.net/alpha/pyscript.js"></script>
+      <py-env>
+        - numpy
+        - matplotlib
+      </py-env>
+    </head>
+
+  <body>
+    <h1>Let's plot random numbers</h1>
+    <div id="plot"></div>
+    <py-script output="plot">
+import matplotlib.pyplot as plt
+import numpy as np
+
+x = np.random.randn(1000)
+y = np.random.randn(1000)
+
+fig, ax = plt.subplots()
+ax.scatter(x, y)
+fig
+    </py-script>
+  </body>
+</html>
+```
+
+### Local modules
+
+In addition to packages, you can declare local Python modules that will
+be imported in the `<py-script>` tag. For example, we can place the random
+number generation steps in a function in the file `data.py`.
+
+```python
+# data.py
+import numpy as np
+
+
+def make_x_and_y(n):
+    x = np.random.randn(n)
+    y = np.random.randn(n)
+    return x, y
+```
+
+In the HTML tag `<py-env>`, paths to local modules are provided in the
+`paths:` key.
+
+```html
+<html>
+    <head>
+      <link rel="stylesheet" href="https://pyscript.net/alpha/pyscript.css" />
+      <script defer src="https://pyscript.net/alpha/pyscript.js"></script>
+      <py-env>
+        - numpy
+        - matplotlib
+        - paths:
+          - /data.py
+      </py-env>
+    </head>
+
+  <body>
+    <h1>Let's plot random numbers</h1>
+    <div id="plot"></div>
+    <py-script output="plot">
+import matplotlib.pyplot as plt
+from data import make_x_and_y
+
+x, y = make_x_and_y(n=1000)
+
+fig, ax = plt.subplots()
+ax.scatter(x, y)
+fig
+    </py-script>
+  </body>
+</html>
+```

docs/tutorials/index.md

@@ -0,0 +1,12 @@
+# Tutorials
+
+This is the tutorials section for beginners.
+
+```{toctree}
+---
+maxdepth: 2
+---
+getting-started
+deployment
+setup
+```

docs/tutorials/setup.md

@@ -0,0 +1,3 @@
+# Setup
+
+**Coming soon!**