jprdonnelly/pyscript
1
0
Fork 0
mirror of https://github.com/pyscript/pyscript.git synced 2025-12-19 10:17:23 -05:00
Code Issues Projects Releases Wiki Activity

Documentation infrastructure. (#262)

Browse Source 
* 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>
This commit is contained in:
Jannis Leidel
2022-05-17 19:08:06 +02:00
committed by GitHub
parent eb3a31a698
commit 6898daf0ce
34 changed files with 665 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
.github/workflows/docs-latest.yml vendored Normal file
View File

@@ -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/

59
.github/workflows/docs-release.yml vendored Normal file
View File

@@ -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 }}/

74
.github/workflows/docs-review.yml vendored Normal file
View File

@@ -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

1
.gitignore vendored
View File

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

11
.pre-commit-config.yaml
View File

@@ -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

28
.readthedocs.yml Normal file
View File

@@ -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

2
CODE_OF_CONDUCT.md
View File

@@ -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

2
GOVERNANCE.md
View File

@@ -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.

7
MAINTAINERS.md
View File

@@ -1,9 +1,9 @@
# 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 |
@@ -12,6 +12,7 @@ This document lists the Maintainers of the Project. Maintainers may be added onc
| 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/).

2
README.md
View File

@@ -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).

45
docs/Makefile Normal file
View File

@@ -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)

16
docs/README.md Normal file
View File

@@ -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.

44
docs/_static/examples/what-is-pyscript.html vendored Normal file
View File

@@ -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>

BIN
docs/_static/fonts/Hack-Bold.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_static/fonts/Hack-BoldItalic.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_static/fonts/Hack-Italic.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_static/fonts/Hack-Regular.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_static/images/avatar.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

1
docs/_static/redirect.html vendored Normal file
View File

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

1
docs/concepts/governance/maintainers.md Symbolic link
View File

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

1
docs/concepts/governance/policy.md Symbolic link
View File

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

12
docs/concepts/index.md Normal file
View File

@@ -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/*
```

32
docs/concepts/what-is-pyscript.md Normal file
View File

@@ -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>
```
:::
::::

102
docs/conf.py Normal file
View File

@@ -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",
]

16
docs/environment.yml Normal file
View File

@@ -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

18
docs/howtos/index.md Normal file
View File

@@ -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:'
---
*
```

54
docs/index.md Normal file
View File

@@ -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
```

35
docs/make.bat Normal file
View File

@@ -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

4
docs/reference/index.md Normal file
View File

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

5
docs/robots.txt Normal file
View File

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

3
docs/tutorials/deployment.md Normal file
View File

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

31
GETTING-STARTED.md → docs/tutorials/getting-started.md
View File

@@ -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
<html>
@@ -39,14 +39,13 @@ open an HTML by double clicking it in your file explorer.
```
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 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 `<py-script>` 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
<html>
@@ -73,12 +72,12 @@ print(s)
### 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
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
For example, we'll add some style elements and provide place holders for
the `<py-script>` 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 `<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)
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>
@@ -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 `<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>
@@ -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 `<py-script>` 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 `<py-env>` paths to local modules are provided in the
In the HTML tag `<py-env>`, paths to local modules are provided in the
`paths:` key.
```html

12
docs/tutorials/index.md Normal file
View File

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

3
docs/tutorials/setup.md Normal file
View File

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