diff --git a/.github/workflows/docs-latest.yml b/.github/workflows/docs-latest.yml new file mode 100644 index 00000000..277ccd49 --- /dev/null +++ b/.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/ diff --git a/.github/workflows/docs-release.yml b/.github/workflows/docs-release.yml new file mode 100644 index 00000000..4cc50c86 --- /dev/null +++ b/.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 }}/ diff --git a/.github/workflows/docs-review.yml b/.github/workflows/docs-review.yml new file mode 100644 index 00000000..dfbac887 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index 86b04373..57b6b6b3 100644 --- a/.gitignore +++ b/.gitignore @@ -71,6 +71,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/_env/ # PyBuilder target/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e583aa1b..b6e23d2c 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..78adcb2e --- /dev/null +++ b/.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 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 14e7620f..66e416d3 100644 --- a/CODE_OF_CONDUCT.md +++ b/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 diff --git a/GOVERNANCE.md b/GOVERNANCE.md index a9773c11..4baa1d88 100644 --- a/GOVERNANCE.md +++ b/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. diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 72f6d061..58d4eee6 100644 --- a/MAINTAINERS.md +++ b/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/). diff --git a/README.md b/README.md index 152b5f77..fafe77a1 100644 --- a/README.md +++ b/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). diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..cc455c57 --- /dev/null +++ b/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) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..959c8d34 --- /dev/null +++ b/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. diff --git a/docs/_static/examples/what-is-pyscript.html b/docs/_static/examples/what-is-pyscript.html new file mode 100644 index 00000000..d8b96dfd --- /dev/null +++ b/docs/_static/examples/what-is-pyscript.html @@ -0,0 +1,44 @@ + + + + + + + - numpy + - matplotlib + + + + +

Let's plot random numbers

+
+
+

❰py❱

+
+
+ +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) + + + diff --git a/docs/_static/fonts/Hack-Bold.woff b/docs/_static/fonts/Hack-Bold.woff new file mode 100644 index 00000000..35feb8f8 Binary files /dev/null and b/docs/_static/fonts/Hack-Bold.woff differ diff --git a/docs/_static/fonts/Hack-BoldItalic.woff b/docs/_static/fonts/Hack-BoldItalic.woff new file mode 100644 index 00000000..30e7b66c Binary files /dev/null and b/docs/_static/fonts/Hack-BoldItalic.woff differ diff --git a/docs/_static/fonts/Hack-Italic.woff b/docs/_static/fonts/Hack-Italic.woff new file mode 100644 index 00000000..037a0b3e Binary files /dev/null and b/docs/_static/fonts/Hack-Italic.woff differ diff --git a/docs/_static/fonts/Hack-Regular.woff b/docs/_static/fonts/Hack-Regular.woff new file mode 100644 index 00000000..05ea5cf9 Binary files /dev/null and b/docs/_static/fonts/Hack-Regular.woff differ diff --git a/docs/_static/images/avatar.jpg b/docs/_static/images/avatar.jpg new file mode 100644 index 00000000..538af057 Binary files /dev/null and b/docs/_static/images/avatar.jpg differ diff --git a/docs/_static/redirect.html b/docs/_static/redirect.html new file mode 100644 index 00000000..3c3a36bc --- /dev/null +++ b/docs/_static/redirect.html @@ -0,0 +1 @@ + diff --git a/docs/concepts/governance/maintainers.md b/docs/concepts/governance/maintainers.md new file mode 120000 index 00000000..eebb1838 --- /dev/null +++ b/docs/concepts/governance/maintainers.md @@ -0,0 +1 @@ +../../../MAINTAINERS.md \ No newline at end of file diff --git a/docs/concepts/governance/policy.md b/docs/concepts/governance/policy.md new file mode 120000 index 00000000..46072977 --- /dev/null +++ b/docs/concepts/governance/policy.md @@ -0,0 +1 @@ +../../../GOVERNANCE.md \ No newline at end of file diff --git a/docs/concepts/index.md b/docs/concepts/index.md new file mode 100644 index 00000000..8bd09c78 --- /dev/null +++ b/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/* +``` diff --git a/docs/concepts/what-is-pyscript.md b/docs/concepts/what-is-pyscript.md new file mode 100644 index 00000000..0c847c1f --- /dev/null +++ b/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 `` 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 + +``` + +::: +:::: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..c6af21b2 --- /dev/null +++ b/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", +] diff --git a/docs/environment.yml b/docs/environment.yml new file mode 100644 index 00000000..e21bf628 --- /dev/null +++ b/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 diff --git a/docs/howtos/index.md b/docs/howtos/index.md new file mode 100644 index 00000000..5c4261fe --- /dev/null +++ b/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:' +--- +* +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..4d2a62fc --- /dev/null +++ b/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 +``` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..32bb2452 --- /dev/null +++ b/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 diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 00000000..f798f587 --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,4 @@ +# Reference + +This reference section will have manually documented or fully +automated code documentation. **Coming soon!** diff --git a/docs/robots.txt b/docs/robots.txt new file mode 100644 index 00000000..4fccf0cc --- /dev/null +++ b/docs/robots.txt @@ -0,0 +1,5 @@ +User-agent: * +Disallow: /review/ + +Sitemap: https://docs.pyscript.net/sitemap.xml +Host: docs.pyscript.net diff --git a/docs/tutorials/deployment.md b/docs/tutorials/deployment.md new file mode 100644 index 00000000..5ed82887 --- /dev/null +++ b/docs/tutorials/deployment.md @@ -0,0 +1,3 @@ +# Deployment + +**Coming soon!** diff --git a/GETTING-STARTED.md b/docs/tutorials/getting-started.md similarity index 84% rename from GETTING-STARTED.md rename to docs/tutorials/getting-started.md index bb1e1722..8e3d16d2 100644 --- a/GETTING-STARTED.md +++ b/docs/tutorials/getting-started.md @@ -13,7 +13,7 @@ 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 +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 @@ -23,10 +23,10 @@ the instructions in the README.md file. Here's a "Hello, world!" example using PyScript. -Using your favorite editor create a new file called `hello.html` in +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. +open an HTML by double-clicking it in your file explorer. ```html @@ -39,14 +39,13 @@ open an HTML by double clicking it in your file explorer. ``` Notice the use of the `` tag in the HTML body. This -is where you'll write your Python code. In the following sections we'll -introduce the 8 tags provided by PyScript. +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 `` tag lets you execute multi-line Python scripts and -print back onto the page. For -example, we can compute π. +print back onto the page. For example, we can compute π. ```html @@ -73,12 +72,12 @@ print(s) ### Writing into labeled elements -In the example above we had a single `` tag and it printed -one or more lines onto the page in order. Within the `` you +In the example above, we had a single `` tag and it printed +one or more lines onto the page in order. Within the ``, 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 +For example, we'll add some style elements and provide place holders for the `` tag write to. ```html @@ -115,8 +114,8 @@ pyscript.write('pi', f'π is approximately {pi:.3f}') 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 `` 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) +In order to use them, you will need to declare the dependencies using the `` 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). ``` @@ -125,12 +124,11 @@ HTML head. You can also link to `.whl` files directly on disk like in our [toga ``` 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. +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 `` as a shortcut, which takes the expression on the last line of the script and runs `pyscript.write('plot', fig)`. - ```html @@ -162,7 +160,7 @@ fig ### Local modules -In addition to packages you can declare local Python modules that will +In addition to packages, you can declare local Python modules that will be imported in the `` tag. For example, we can place the random number generation steps in a function in the file `data.py`. @@ -170,13 +168,14 @@ number generation steps in a function in the file `data.py`. # 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 `` paths to local modules are provided in the +In the HTML tag ``, paths to local modules are provided in the `paths:` key. ```html diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 00000000..d19d033c --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,12 @@ +# Tutorials + +This is the tutorials section for beginners. + +```{toctree} +--- +maxdepth: 2 +--- +getting-started +deployment +setup +``` diff --git a/docs/tutorials/setup.md b/docs/tutorials/setup.md new file mode 100644 index 00000000..dab30d7f --- /dev/null +++ b/docs/tutorials/setup.md @@ -0,0 +1,3 @@ +# Setup + +**Coming soon!**