From 0af8ccab2e911134ae55dcc49fa909e6585273ee Mon Sep 17 00:00:00 2001 From: "Nicholas H.Tollervey" Date: Mon, 2 Oct 2023 17:05:42 +0100 Subject: [PATCH] Updates to the user-guide, addition of a developer guide, minor corrections and update to the developer instructions in the README (we use venv/pip). --- Makefile | 46 ------- README.md | 11 +- docs/developers.md | 261 ++++++++++++++++++++++++++++++++++++++++ docs/index.md | 16 ++- docs/user-guide.md | 293 ++++++++++++++++++++++++++++++++------------- environment.yml | 9 -- requirements.txt | 2 + 7 files changed, 491 insertions(+), 147 deletions(-) delete mode 100644 Makefile create mode 100644 docs/developers.md delete mode 100644 environment.yml create mode 100644 requirements.txt diff --git a/Makefile b/Makefile deleted file mode 100644 index af47bc0..0000000 --- a/Makefile +++ /dev/null @@ -1,46 +0,0 @@ -# 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: html - @echo 'visit docs at http://localhost:8080' - python -m http.server -d "$(BUILDDIR)/html/" 8080 - -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/README.md b/README.md index 07e80b9..36a7da7 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ # PyScript documentation -Welcome to the PyScript documentation directory, where you can find -and contribute to discussions around PyScript and related topics. +Welcome to the PyScript documentation repository. + +Contribute prose and participate in discussions about the written support of +PyScript and related topics. ## Getting started @@ -16,8 +18,9 @@ The `docs` directory in the pyscript repository contains a that takes plaintext files containing documentation written in Markdown, along with static files like templates and themes, to build the static end result. -To setup the documentation development environment simply run `make setup` from this folder and, once it's done, -activate your environment by running `conda activate ./_env` +To setup the documentation development environment simply create a new +virtual environment, then `pip install -r requirements.txt` (from in the root +of this repository). ## Build diff --git a/docs/developers.md b/docs/developers.md new file mode 100644 index 0000000..8db28fd --- /dev/null +++ b/docs/developers.md @@ -0,0 +1,261 @@ +# Developer Guide + +This page explains the technical and practical requirements and processes +needed to contribute to PyScript. + +!!! info + + In the following instructions, we assume familiarity with `git`, + [GitHub](https://github.com/pyscript/pyscript), the command line and other + common development concepts, tools and practices. + + For those who come from a non-Pythonic technical background (for example, + you're a JavaScript developer), we will explain Python-isms as we go along + so you're contributing with confidence. + + If you're unsure, or encounter problems, please ask for help on our + [discord server](https://discord.gg/HxvBtukrg2). + +## Welcome + +We are a diverse, inclusive coding community and welcome contributions from +_anyone_ irrespective of their background. If you're thinking, "but they don't +mean me", _then we especially mean YOU_. Our diversity means _you will meet +folks in our community who are different to yourself_. Therefore, thoughtful +contributions made in good faith, and engagement with respect, care and +compassion wins every time. + +* If you're from a background which isn't well-represented in most geeky + groups, get involved - _we want to help you make a difference_. +* If you're from a background which **is** well-represented in most geeky + groups, get involved - _we want your help making a difference_. +* If you're worried about not being technical enough, get involved - _your + fresh perspective will be invaluable_. +* If you need help with anything, get involved - _we welcome questions asked + in good faith, and will move mountains to help_. +* If you're unsure where to start, get involved - _we have [many ways to + contribute](/contributing)_. + +All contributors are expected to follow our [code of conduct](/conduct/). + +## Setup + +**You must have recent versions of [Python](https://python.org/), +[node.js](https://nodejs.org/en) and [npm](https://www.npmjs.com/) already +installed on your system.** + +The following steps create a working development environment for PyScript. It +is through this environment that you contribute to PyScript. + +!!! danger + + The following commands work on Unix like operating systems (like MacOS or + Linux). **If you are a Microsoft Windows user please use the + [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/about) + with the following instructions.** + +### Create a virtual environment + +* A Python [virtual environment](https://docs.python.org/3/library/venv.html) + is a computing "sandbox" that safely isolates your work. PyScript's + development makes use of various Python based tools, so both + [Python](https://python.org) and a virtual environment is needed. There are + many tools to help manage these environments, but the standard way to create + a virtual environment is to use this command in your terminal: + + ```sh + python3 -m venv my_pyscript_dev_venv + ``` + + !!! warning + + Replace `my_pyscript_dev_venv` with a meaningful name for the + virtual environment, that works for you. + +* A `my_pyscript_dev_venv` directory containing the virtual environment's + "stuff" is created as a subdirectory of your current directory. Next, + activate the virtual environment to ensure your development activities happen + within the context of the sandbox: + + ```sh + source my_pyscript_dev_venv/bin/activate + ``` + +* The prompt in your terminal will change to include the name of your virtual + environment indicating the sandbox is active. To deactivate the virtual + environment just type the following into your terminal: + + ```sh + deactivate + ``` + +!!! info + + The rest of the instructions on this page assume you are working in **an + activated virtual environment** for developing PyScript. + +### Prepare your repository + +* Create a [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) + of the + [PyScript github repository](https://github.com/pyscript/pyscript/fork) to + your own GitHub account. +* [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) + your newly forked version of the PyScript repository onto your + local development machine. For example, use this command in your terminal: + + ```sh + git clone https://github.com//pyscript + ``` + + !!! warning + + In the URL for the forked PyScript repository, remember to replace + `` with your actual GitHub username. + + !!! tip + + To help explain steps, we will use `git` commands to be typed into your + terminal / command line. + + The equivalent of these commands could be achieved through other means + (such as [GitHub's desktop client](https://desktop.github.com/)). How + these alternatives work is beyond the scope of this document. + +* Change into the root directory of your newly cloned `pyscript` repository: + + ```sh + cd pyscript + ``` + +* Add the original PyScript repository as your `upstream` to allow you to keep + your own fork up-to-date with the latest changes: + + ```sh + git remote add upstream https://github.com/pyscript/pyscript.git + ``` + +* If the above fails, try this alternative: + + ```sh + git remote remove upstream + git remote add upstream git@github.com:pyscript/pyscript.git + ``` + +* Pull in the latest changes from the main `upstream` PyScript repository: + + ```sh + git pull upstream main + ``` + +* Pyscript uses a `Makefile` to automate the most common development tasks. In + your terminal, type `make` to see what it can do. You should see something + like this: + + ```sh + There is no default Makefile target right now. Try: + + make setup - check your environment and install the dependencies. + make clean - clean up auto-generated assets. + make build - build PyScript. + make precommit-check - run the precommit checks (run eslint). + make test-integration - run all integration tests sequentially. + make fmt - format the code. + make fmt-check - check the code formatting. + ``` + +### Install dependencies + +* To install the required software dependencies for working on PyScript, in + your terminal type: + + ```sh + make setup + ``` + +* Updates from `npm` and then `pip` will scroll past telling you about + their progress installing the required packages. + + !!! warning + + The `setup` process checks the versions of Python, node + and npm. If you encounter a failure at this point, it's probably + because one of these pre-requisits is out of date on your system. + Please update! + +## Check code + +* To ensure consistency of code layout we use tools to both reformat and check + the code. + +* To ensure your code is formatted correctly: + + ```sh + make fmt + ``` + +* To check your code is formatted correctly: + + ```sh + make fmt-check + ``` + +* Finally, as part of the automated workflow for contributing + [pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) + pre-commit checks the source code. If this fails revise your PR. To run + pre-commit checks locally (before creating the PR): + + ```sh + make precommit-check + ``` + + This may also revise your code formatting. Re-run `make precommit-check` to + ensure this is the case. + +## Build PyScript + +* To turn the JavaScript source code found in the `pyscript.core` directory + into a bundled up module ready for the browser, type: + + ```sh + make build + ``` + + The resulting assets will be in the `pyscript.core/dist` directory. + +## Run the tests + +* The integration tests for PyScript are started with: + + ```sh + make test-integration + ``` + +## Documentation + +* Documentation for PyScript (i.e. what you're reading right now), is found + in a separate repository: + [https://github.com/pyscript/docs](https://github.com/pyscript/docs) + +* The documentation's `README` file contains instructions for setting up a + development environment and contributing. + +## Contributing + +* We have [suggestions for how to contribute to PyScript](/contributing). Take + a read and dive in. + +* Please make sure you discuss potential contributions *before* you put in + work. We don#t want folks to waste their time or re-invent the wheel. + +* Technical discussions happen [on our discord server](https://discord.gg/HxvBtukrg2) + and in the + [discussions section](https://github.com/pyscript/pyscript/discussions) of + our GitHub repository. + +* Every Tusday is a community video call, the details of which are posted onto + the discord server. Face to face technical discussions happen here. + +* Every two weeks, on a Thursday, is a PyScript FUN call, the details of which + are also posted to discord. Project show-and-tells, cool hacks, new features + and a generally humorous and creative time is had by all. diff --git a/docs/index.md b/docs/index.md index 97c97b2..498e065 100644 --- a/docs/index.md +++ b/docs/index.md @@ -31,6 +31,15 @@
The beginner docs will set you up with a simple coding environment. For more in-depth technical coverage of PyScript, consult the user guide.
+
I want to contribute...
+
+

Welcome, friend! + PyScript is an open source project, we expect participants to act in + the spirit of our code of conduct and we have many + ways in which you can contribute. + Our developer guide explains how to set + up a working development environment for PyScript.

+
Just show me...
That's easy! Just take a look around pyscript.com.
@@ -38,11 +47,8 @@

Join in with the conversation on our discord server, - for realtime chat with core maintainers and fellow users of PyScript.

-

Find out more about the open source project, who is involved and how - you could contribute or support our efforts via the - contributor's guide.

-

Explore + for realtime chat with core maintainers and fellow users of PyScript. + Explore educational and commercial diff --git a/docs/user-guide.md b/docs/user-guide.md index 5643df3..c637501 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -10,15 +10,14 @@ or web development experience. If you're a beginner start with our [beginner's guide](beginning-pyscript.md). - We [welcome feedback](https://github.com/pyscript/docs/issues) to help us - improve. + We [welcome constructive feedback](https://github.com/pyscript/docs/issues). This guide has three aims: -1. A clear overview, context setting and sign-posting for all things PyScript. -2. Exploration of PyScript in substantial technical detail. -3. Demonstration of the features of PyScript working together in real-world - example applications. +1. A [clear overview](#what-is-pyscript) of all things PyScript. +2. [Exploration of PyScript](#architecture) in substantial technical detail. +3. Demonstration of the features of PyScript working together in + [real-world example applications](#examples). _Read this page in full_: it is a short but comprehensive overview of the PyScript platform. @@ -30,14 +29,15 @@ projects with PyScript. Should you wish to engage with the development of PyScript, you are welcome to contribute via [the project's GitHub organisation](https://github.com/pyscript). -Finally, the examples listed at the end of this page are all freely available +Finally, the projects at the end of this page are all freely available and copiously commented on [pyscript.com](https://pyscript.com). !!! note Many of these examples come from contributors in our wonderful - community. If you believe you have a project that would make a good - demonstration, please don't hesitate to + community. We love to recognise, amplify and celebrate the incredible work + of folks in the PyScript community. If you believe you have a project that + would make a good demonstration, please don't hesitate to [get in touch](https://discord.gg/HxvBtukrg2). ## What is PyScript? @@ -93,10 +93,10 @@ the planet who use computers.

PyScript brings you two Python interpreters:

    -
  1. Pyodide - the original standard +
  2. Pyodide - the original standard CPython interpreter you know and love, but compiled to WebAssembly.
    3. -
  3. MicroPython - a lean and +
  4. MicroPython - a lean and efficient reimplementation of Python3 that includes a comprehensive subset of the standard library, compiled to WebAssembly.
@@ -135,9 +135,9 @@ the planet who use computers. web workers expensive and blocking computation can run somewhere other than the main application thread controlling the user interface. When such work is done - on the main thread, the browser appears frozen and web workers ensure - expensive blocking computation can happen elsewhere. Think of workers as - independent subprocesses in your web page.
+ on the main thread, the browser appears frozen; web workers ensure + expensive blocking computation happens elsewhere. + Think of workers as independent subprocesses in your web page.
Rich and powerful plugins
@@ -203,16 +203,16 @@ file containing your code, or inline your code between the opening and closing tags. **We recommend you use the `src` attribute method**, but retain the ability to include code between tags for convenience. -Here's a ` ``` ...and here's a `` tag with inline Python code. -```html title="Using a py-script tag with inline code" +```html title="A <py-script> tag with inline code" import sys from pyscript import display @@ -229,16 +229,27 @@ attributes: referenced file is evaluated instead. **This is the recommended way to reference your Python code.** * `config` - your code will only be evaluated after the referenced - configuration has been parsed. Since configuration can be JSON (or a TOML - file), `config='{"packages":["numpy"]}'` and `config="./config.json"` or + [configuration](#configuration) has been parsed. Since configuration can be + JSON or a TOML file, + `config='{"packages":["numpy"]}'` and `config="./config.json"` or `config="./config.toml"` are all valid. * `async` - your Python code can contain a [top level await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await). -* `worker` - a flag to indicate your Python code is to be run on a web worker - instead of the "main thread" that looks after the user interface. +* `worker` - a flag to indicate your Python code is to be run on a + [web worker](#workers) instead of the "main thread" that looks after the user + interface. * `target` - The id or selector of the element where calls to [`display()`](#pyscriptdisplay) should write their values. +!!! warning + + The `packages` setting used in the example configuration shown above is a + **Pyodide-only feature** because MicroPython doesn't support code packaged + on PyPI. + + For more information please refer to the [packages section](#packages) of + this user guide. + !!! question Why do we recommend use of the ` ``` - Notice how different interpreters can be used in different contexts. + Notice how different interpreters can be used with different + configurations. ## Architecture -There are two important aspects of PyScript's architecture: +PyScript's architecture has two core concepts: 1. A small, efficient and powerful kernel called [PolyScript](https://github.com/pyscript/polyscript) is the foundation upon which PyScript and plugins are built. 2. The PyScript [stack](https://en.wikipedia.org/wiki/Solution_stack) inside - the browser is easy to understand. + the browser is simple and clearly defined. ### PolyScript @@ -358,8 +370,8 @@ application relate to each other: !!! failure - Python solely running in the browser is an unfamiliar concept that some - fail to remember. + PyScript is simply Python running in the browser. It is an unfamiliar + concept that some fail to remember. * PyScript isn't running on a server hosted in the cloud. * PyScript doesn't use the version of Python running natively on the user's @@ -395,9 +407,9 @@ Here's how PyScript unfolds through time: the HTML is fully parsed. * The PyScript module does broadly six things: 1. Discover Python code referenced in the page. - 2. Evaluate any [configuration](#configuration) on the page (either via a - single `` tag or the `config` attribute of a ` ``` -Of course, code running in the worker needs to be able to access the web page -running in the main thread. This is achieved via some builtin helper utilities -described in the next section. +Code running in the worker needs to be able to access the web page running in +the main thread. This is achieved via builtin helper utilities described in the +next section. !!! note - The worker related functionality in PyScript is, for the sake of ease of - use, a simpler presentation of more sophisticated and powerful behaviour + For ease of use, the worker related functionality in PyScript is + a simpler presentation of more sophisticated and powerful behaviour available via PolyScript. - Please [consult the XWorker](https://pyscript.github.io/polyscript/#xworker) + **If you are a confident advanced user**, please + [consult the XWorker](https://pyscript.github.io/polyscript/#xworker) related documentation from the PolyScript project for how to make use of these features. ## Builtin helpers -PyScript makes available various convenience objects and functions inside +PyScript makes available convenience objects and functions inside Python. This is done via the `pyscript` module: ```python title="Accessing the document object via the pyscript module" @@ -921,7 +1009,8 @@ This object is a proxy for the web page's Please note that in workers, this is still the main window, not the worker's own global context. A worker's global context is reachable instead - via `import js` (the `js` object being a proxy for `globalThis`). + via `import js` (the `js` object being a proxy for the worker's + `globalThis`). #### `pyscript.document` @@ -941,7 +1030,7 @@ The `display` function takes a list of `*values` as its first argument, and has two optional named arguments: * `target=None` - the DOM element into which the content should be placed. -* `append=False` - a flag to indicate if the output is going to be appended to +* `append=True` - a flag to indicate if the output is going to be appended to the `target`. There are some caveats: @@ -949,12 +1038,50 @@ There are some caveats: * When used in the main thread, the `display` function automatically uses the current `