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 executablebooks/mdformat-myst#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>

.github/workflows/docs-latest.yml

@@ -0,0 +1,58 @@
+name: '[Docs] Build Latest'
+
+on:
+    push:
+        branches:
+        -   main
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            id-token: write
+        env:
+            SPHINX_HTML_BASE_URL: https://docs.pyscript.net/
+        steps:
+
+        -   name: Checkout
+            uses: actions/checkout@v3
+            with:
+                persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal access token.
+                fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
+
+        -   name: Setup
+            uses: conda-incubator/setup-miniconda@v2
+            with:
+                auto-update-conda: true
+                activate-environment: docs
+                environment-file: docs/environment.yml
+                python-version: '3.9'
+
+        -   name: Build
+            shell: bash -l {0}
+            run: |
+                cd docs/
+                make html
+
+        -   name: Upload artifacts
+            uses: actions/upload-artifact@v3
+            with:
+                name: pyscript-docs-latest
+                path: docs/_build/html/
+
+        # Deploy to S3
+        -   name: Configure AWS credentials
+            uses: aws-actions/configure-aws-credentials@v1.6.1
+            with:
+                aws-region: ${{secrets.AWS_REGION}}
+                role-to-assume: ${{ secrets.AWS_OIDC_RUNNER_ROLE }}
+
+        -   name: Copy redirect file
+            run: aws s3 cp --quiet ./docs/_build/html/_static/redirect.html s3://docs.pyscript.net/index.html
+
+        # -   name: Delete latest directory
+        #     run: aws s3 rm --recursive s3://docs.pyscript.net/latest/
+
+        -   name: Sync to S3
+            run: aws s3 sync --quiet ./docs/_build/html/ s3://docs.pyscript.net/latest/

.github/workflows/docs-release.yml

@@ -0,0 +1,59 @@
+name: '[Docs] Build Release'
+
+on:
+  # Any time a tag or branch is created
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#create
+    create:
+
+jobs:
+    build:
+        if: startsWith(github.ref, 'refs/tags') # Only if tagged
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            id-token: write
+        env:
+            SPHINX_HTML_BASE_URL: https://docs.pyscript.net/
+        steps:
+
+        -   name: Checkout
+            uses: actions/checkout@v3
+            with:
+                persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal access token.
+                fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
+
+        -   name: Setup
+            uses: conda-incubator/setup-miniconda@v2
+            with:
+                auto-update-conda: true
+                activate-environment: docs
+                environment-file: docs/environment.yml
+                python-version: '3.9'
+
+        -   name: Build
+            shell: bash -l {0}
+            run: |
+                cd docs/
+                make html
+
+        -   name: Upload artifacts
+            uses: actions/upload-artifact@v3
+            with:
+                name: pyscript-docs-${{ github.ref_name }}
+                path: docs/_build/html/
+
+        # Deploy to S3
+        -   name: Configure AWS credentials
+            uses: aws-actions/configure-aws-credentials@v1.6.1
+            with:
+                aws-region: ${{secrets.AWS_REGION}}
+                role-to-assume: ${{ secrets.AWS_OIDC_RUNNER_ROLE }}
+
+        -   name: Copy redirect file
+            run: aws s3 cp --quiet ./docs/_build/html/_static/redirect.html s3://docs.pyscript.net/index.html
+
+        # -   name: Delete release directory
+        #     run: aws s3 rm --recursive s3://docs.pyscript.net/${{ github.ref_name }}/
+
+        -   name: Sync to S3
+            run: aws s3 sync --quiet ./docs/_build/html/ s3://docs.pyscript.net/${{ github.ref_name }}/

.github/workflows/docs-review.yml

@@ -0,0 +1,74 @@
+name: '[Docs] Build Review'
+
+on:
+    pull_request:
+        branches:
+        -   '*'
+
+concurrency:
+  # Concurrency group that uses the workflow name and PR number if available
+  # or commit SHA as a fallback. If a new build is triggered under that
+  # concurrency group while a previous build is running it will be canceled.
+  # Repeated pushes to a PR will cancel all previous builds, while multiple
+  # merges to main will not cancel.
+    group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+    cancel-in-progress: true
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            id-token: write
+        env:
+            SPHINX_HTML_BASE_URL: https://docs.pyscript.net/
+        steps:
+
+        -   name: Checkout
+            uses: actions/checkout@v3
+            with:
+                persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal access token.
+                fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
+
+        -   name: Setup
+            uses: conda-incubator/setup-miniconda@v2
+            with:
+                auto-update-conda: true
+                activate-environment: docs
+                environment-file: docs/environment.yml
+                python-version: '3.9'
+
+        -   name: Build
+            shell: bash -l {0}
+            run: |
+                cd docs/
+                make html
+
+        -   name: Upload artifacts
+            uses: actions/upload-artifact@v3
+            with:
+                name: pyscript-docs-review-${{ github.event.number }}
+                path: docs/_build/html/
+
+        # Deploy to S3
+        -   name: Configure AWS credentials
+            uses: aws-actions/configure-aws-credentials@v1.6.1
+            with:
+                aws-region: ${{secrets.AWS_REGION}}
+                role-to-assume: ${{ secrets.AWS_OIDC_RUNNER_ROLE }}
+
+        -   name: Copy redirect file
+            run: aws s3 cp --quiet ./docs/_build/html/_static/redirect.html s3://docs.pyscript.net/index.html
+
+        # -   name: Delete review directory
+        #     run: aws s3 rm --recursive s3://docs.pyscript.net/review/${{ github.event.number }}/
+
+        -   name: Sync to S3
+            run: aws s3 sync --quiet ./docs/_build/html/ s3://docs.pyscript.net/review/${{ github.event.number }}/
+
+        -   name: Adding step summary
+            run: |
+                echo "### Review documentation" >> $GITHUB_STEP_SUMMARY
+                echo "As with any pull request, you can find the rendered documentation version for pull request ${{ github.event.number }} here:"
+                echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
+                echo "https://docs.pyscript.net/review/${{ github.event.number }}/" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -71,6 +71,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_env/
 
 # PyBuilder
 target/

.pre-commit-config.yaml

@@ -75,3 +75,14 @@ repos:
         -   typescript
         -   '@typescript-eslint/eslint-plugin'
         -   '@typescript-eslint/parser'
+
+# Commented out until mdformat-myst supports custom extensions
+# See https://github.com/executablebooks/mdformat-myst/pull/9
+# -   repo: https://github.com/executablebooks/mdformat
+#     rev: 0.7.14 # Use the ref you want to point at
+#     hooks:
+#     -   id: mdformat
+#         additional_dependencies:
+#         -   mdformat-gfm
+#         -   mdformat-myst
+#         -   mdformat-black

.readthedocs.yml

@@ -0,0 +1,28 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+    os: ubuntu-20.04
+    tools:
+        python: miniconda3-4.7
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+    configuration: docs/conf.py
+
+conda:
+    environment: docs/environment.yml
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+    install:
+    -   requirements: docs/requirements.txt

CODE_OF_CONDUCT.md

@@ -1,4 +1,4 @@
 # Code of Conduct
 
-The Code of Conduct is available in the pyscript Governance repo.
+The Code of Conduct is available in the PyScript Governance repo.
 See https://github.com/pyscript/governance/blob/main/CODE-OF-CONDUCT.md

GOVERNANCE.md

@@ -1,6 +1,6 @@
 # Governance Policy
 
-This document provides the governance policy for the Project. Maintainers agree to this policy and to abide by all Project polices, including the [code of conduct](https://github.com/pyscript/governance/blob/main/CODE-OF-CONDUCT.md), [trademark policy](https://github.com/pyscript/governance/blob/main/TRADEMARKS.md), and [antitrust policy](https://github.com/pyscript/governance/blob/main/ANTITRUST.md) by adding their name to the [maintainers.md file](./MAINTAINERS.md).
+This document provides the governance policy for the Project. Maintainers agree to this policy and to abide by all Project policies, including the [code of conduct](https://github.com/pyscript/governance/blob/main/CODE-OF-CONDUCT.md), [trademark policy](https://github.com/pyscript/governance/blob/main/TRADEMARKS.md), and [antitrust policy](https://github.com/pyscript/governance/blob/main/ANTITRUST.md) by adding their name to the [maintainers.md file](https://github.com/pyscript/pyscript/blob/main/MAINTAINERS.md).
 
 ## 1. Roles.
 

MAINTAINERS.md

@@ -1,17 +1,18 @@
 # Maintainers
 
-This document lists the Maintainers of the Project. Maintainers may be added once approved by the existing maintainers as described in the [Governance document](./GOVERNANCE.md). By adding your name to this list you are agreeing to abide by the Project governance documents and to abide by all of the Organization's polices, including the [code of conduct](https://github.com/pyscript/governance/blob/main/CODE-OF-CONDUCT.md), [trademark policy](https://github.com/pyscript/governance/blob/main/TRADEMARKS.md), and [antitrust policy](https://github.com/pyscript/governance/blob/main/TRADEMARKS.md). If you are participating because of your affiliation with another organization (designated below), you represent that you have the authority to bind that organization to these policies.
+This document lists the Maintainers of the Project. Maintainers may be added once approved by the existing maintainers as described in the [Governance document](https://github.com/pyscript/pyscript/blob/main/GOVERNANCE.md). By adding your name to this list you are agreeing to abide by the Project governance documents and to abide by all of the Organization's polices, including the [code of conduct](https://github.com/pyscript/governance/blob/main/CODE-OF-CONDUCT.md), [trademark policy](https://github.com/pyscript/governance/blob/main/TRADEMARKS.md), and [antitrust policy](https://github.com/pyscript/governance/blob/main/TRADEMARKS.md). If you are participating because of your affiliation with another organization (designated below), you represent that you have the authority to bind that organization to these policies.
 
-| **NAME** | **Organization** |
-| --- | --- |
-| Fabio Pliger | Anaconda, Inc |
-| Antonio Cuni | Anaconda, Inc |
-| Philipp Rudiger | Anaconda, Inc |
-| Peter Wang | Anaconda, Inc |
-| Kevin Goldsmith | Anaconda, Inc |
-| Mariana Meireles | Anaconda, Inc |
-| --- | --- |
+| **NAME**         | **Organization** |
+| ---------------- | ---------------- |
+| Fabio Pliger     | Anaconda, Inc    |
+| Antonio Cuni     | Anaconda, Inc    |
+| Philipp Rudiger  | Anaconda, Inc    |
+| Peter Wang       | Anaconda, Inc    |
+| Kevin Goldsmith  | Anaconda, Inc    |
+| Mariana Meireles | Anaconda, Inc    |
+| ---              | ---              |
+
+______________________________________________________________________
 
----
 Part of MVG-0.1-beta.
 Made with love by GitHub. Licensed under the [CC-BY 4.0 License](https://creativecommons.org/licenses/by-sa/4.0/).

README.md

@@ -5,7 +5,7 @@
 ### Summary
 PyScript is a Pythonic alternative to Scratch, JSFiddle, and other "easy to use" programming frameworks, with the goal of making the web a friendly, hackable place where anyone can author interesting and interactive applications.
 
-To get started see [GETTING-STARTED](GETTING-STARTED.md).
+To get started see the [getting started tutorial](docs/tutorials/getting-started.md).
 
 For examples see [the pyscript folder](pyscriptjs).
 

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.