8000 Documentation infrastructure. (#262) · yannickfunk/pyscript@6898daf · GitHub
[go: up one dir, main page]
Skip to content

Commit 6898daf

Browse files
jezdezpre-commit-ci[bot]mattkramximena9201
authored
Documentation infrastructure. (pyscript#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>
1 parent eb3a31a commit 6898daf

34 files changed

+665
-30
lines changed

‎.github/workflows/docs-latest.yml

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: '[Docs] Build Latest'
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
permissions:
12+
contents: read
13+
id-token: write
14+
env:
15+
SPHINX_HTML_BASE_URL: https://docs.pyscript.net/
16+
steps:
17+
18+
- name: Checkout
19+
uses: actions/checkout@v3
20+
with:
21+
persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal access token.
22+
fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
23+
24+
- name: Setup
25+
uses: conda-incubator/setup-miniconda@v2
26+
with:
27+
auto-update-conda: true
28+
activate-environment: docs
29+
environment-file: docs/environment.yml
30+
python-version: '3.9'
31+
32+
- name: Build
33+
shell: bash -l {0}
34+
run: |
35+
cd docs/
36+
make html
37+
38+
- name: Upload artifacts
39+
uses: actions/upload-artifact@v3
40+
with:
41+
name: pyscript-docs-latest
42+
path: docs/_build/html/
43+
44+
# Deploy to S3
45+
- name: Configure AWS credentials
46+
uses: aws-actions/configure-aws-credentials@v1.6.1
47+
with:
48+
aws-region: ${{secrets.AWS_REGION}}
49+
role-to-assume: ${{ secrets.AWS_OIDC_RUNNER_ROLE }}
50+
51+
- name: Copy redirect file
52+
run: aws s3 cp --quiet ./docs/_build/html/_static/redirect.html s3://docs.pyscript.net/index.html
53+
54+
# - name: Delete latest directory
55+
# run: aws s3 rm --recursive s3://docs.pyscript.net/latest/
56+
57+
- name: Sync to S3
58+
run: aws s3 sync --quiet ./docs/_build/html/ s3://docs.pyscript.net/latest/

‎.github/workflows/docs-release.yml

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: '[Docs] Build Release'
2+
3+
on:
4+
# Any time a tag or branch is created
5+
# https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#create
6+
create:
7+
8+
jobs:
9+
build:
10+
if: startsWith(github.ref, 'refs/tags') # Only if tagged
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: read
14+
id-token: write
15+
env:
16+
SPHINX_HTML_BASE_URL: https://docs.pyscript.net/
17+
steps:
18+
19+
- name: Checkout
20+
uses: actions/checkout@v3
21+
with:
22+
persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal access token.
23+
fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
24+
25+
- name: Setup
26+
uses: conda-incubator/setup-miniconda@v2
27+
with:
28+
auto-update-conda: true
29+
activate-environment: docs
30+
environment-file: docs/environment.yml
31+
python-version: '3.9'
32+
33+
- name: Build
34+
shell: bash -l {0}
35+
run: |
36+
cd docs/
37+
make html
38+
39+
- name: Upload artifacts
40+
uses: actions/upload-artifact@v3
41+
with:
42+
name: pyscript-docs-${{ github.ref_name }}
43+
path: docs/_build/html/
44+
45+
# Deploy to S3
46+
- name: Configure AWS credentials
47+
uses: aws-actions/configure-aws-credentials@v1.6.1
48+
with:
49+
aws-region: ${{secrets.AWS_REGION}}
50+
role-to-assume: ${{ secrets.AWS_OIDC_RUNNER_ROLE }}
51+
52+
- name: Copy redirect file
53+
run: aws s3 cp --quiet ./docs/_build/html/_static/redirect.html s3://docs.pyscript.net/index.html
54+
55+
# - name: Delete release directory
56+
# run: aws s3 rm --recursive s3://docs.pyscript.net/${{ github.ref_name }}/
57+
58+
- name: Sync to S3
59+
run: aws s3 sync --quiet ./docs/_build/html/ s3://docs.pyscript.net/${{ github.ref_name }}/

‎.github/workflows/docs-review.yml

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: '[Docs] Build Review'
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- '*'
7+
8+
concurrency:
9+
# Concurrency group that uses the workflow name and PR number if available
10+
# or commit SHA as a fallback. If a new build is triggered under that
11+
# concurrency group while a previous build is running it will be canceled.
12+
# Repeated pushes to a PR will cancel all previous builds, while multiple
13+
# merges to main will not cancel.
14+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
permissions:
21+
contents: read
22+
id-token: write
23+
env:
24+
SPHINX_HTML_BASE_URL: https://docs.pyscript.net/
25+
steps:
26+
27+
- name: Checkout
28+
uses: actions/checkout@v3
29+
with:
30+
persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal access token.
31+
fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
32+
33+
- name: Setup
34+
uses: conda-incubator/setup-miniconda@v2
35+
with:
36+
auto-update-conda: true
37+
activate-environment: docs
38+
environment-file: docs/environment.yml
39+
python-version: '3.9'
40+
41+
- name: Build
42+
shell: bash -l {0}
43+
run: |
44+
cd docs/
45+
make html
46+
47+
- name: Upload artifacts
48+
uses: actions/upload-artifact@v3
49+
with:
50+
name: pyscript-docs-review-${{ github.event.number }}
51+
path: docs/_build/html/
52+
53+
# Deploy to S3
54+
- name: Configure AWS credentials
55+
uses: aws-actions/configure-aws-credentials@v1.6.1
56+
with:
57+
aws-region: ${{secrets.AWS_REGION}}
58+
role-to-assume: ${{ secrets.AWS_OIDC_RUNNER_ROLE }}
59+
60+
- name: Copy redirect file
61+
run: aws s3 cp --quiet ./docs/_build/html/_static/redirect.html s3://docs.pyscript.net/index.html
62+
63+
# - name: Delete review directory
64+
# run: aws s3 rm --recursive s3://docs.pyscript.net/review/${{ github.event.number }}/
65+
66+
- name: Sync to S3
67+
run: aws s3 sync --quiet ./docs/_build/html/ s3://docs.pyscript.net/review/${{ github.event.number }}/
68+
69+
- name: Adding step summary
70+
run: |
71+
echo "### Review documentation" >> $GITHUB_STEP_SUMMARY
72+
echo "As with any pull request, you can find the rendered documentation version for pull request ${{ github.event.number }} here:"
73+
echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
74+
echo "https://docs.pyscript.net/review/${{ github.event.number }}/" >> $GITHUB_STEP_SUMMARY

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ instance/
7171

7272
# Sphinx documentation
7373
docs/_build/
74+
docs/_env/
7475

7576
# PyBuilder
7677
target/

‎.pre-commit-config.yaml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,3 +75,14 @@ repos:
7575
- typescript
7676
- '@typescript-eslint/eslint-plugin'
7777
- '@typescript-eslint/parser'
78+
79+
# Commented out until mdformat-myst supports custom extensions
80+
# See https://github.com/executablebooks/mdformat-myst/pull/9
81+
# - repo: https://github.com/executablebooks/mdformat
82+
# rev: 0.7.14 # Use the ref you want to point at
83+
# hooks:
84+
# - id: mdformat
85+
# additional_dependencies:
86+
# - mdformat-gfm
87+
# - mdformat-myst
88+
# - mdformat-black

‎.readthedocs.yml

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Set the version of Python and other tools you might need
9+
build:
10+
os: ubuntu-20.04
11+
tools:
12+
python: miniconda3-4.7
13+
14+
# Build documentation in the docs/ directory with Sphinx
15+
sphinx:
16+
configuration: docs/conf.py
17+
18+
conda:
19+
environment: docs/environment.yml
20+
21+
# If using Sphinx, optionally build your docs in additional formats such as PDF
22+
# formats:
23+
# - pdf
24+
25+
# Optionally declare the Python requirements required to build your docs
26+
python:
27+
install:
28+
- requirements: docs/requirements.txt

‎CODE_OF_CONDUCT.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# Code of Conduct
22

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

‎GOVERNANCE.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Governance Policy
22

3-
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).
3+
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).
44

55
## 1. Roles.
66

‎MAINTAINERS.md

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,18 @@
11
# Maintainers
22

3-
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.
3+
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.
44

5-
| **NAME** | **Organization** |
6-
| --- | --- |
7-
| Fabio Pliger | Anaconda, Inc |
8-
| Antonio Cuni | Anaconda, Inc |
9-
| Philipp Rudiger | Anaconda, Inc |
10-
| Peter Wang | Anaconda, Inc |
11-
| Kevin Goldsmith | Anaconda, Inc |
12-
| Mariana Meireles | Anaconda, Inc |
13-
| --- | --- |
5+
| **NAME** | **Organization** |
6+
| ---------------- | ---------------- |
7+
| Fabio Pliger | Anaconda, Inc |
8+
| Antonio Cuni | Anaconda, Inc |
9+
| Philipp Rudiger | Anaconda, Inc |
10+
| Peter Wang | Anaconda, Inc |
11+
| Kevin Goldsmith | Anaconda, Inc |
12+
| Mariana Meireles | Anaconda, Inc |
13+
| --- | --- |
14+
15+
______________________________________________________________________
1416

15-
---
1617
Part of MVG-0.1-beta.
1718
Made with love by GitHub. Licensed under the [CC-BY 4.0 License](https://creativecommons.org/licenses/by-sa/4.0/).

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
### Summary
66
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.
77

8-
To get started see [GETTING-STARTED](GETTING-STARTED.md).
8+
To get started see the [getting started tutorial](docs/tutorials/getting-started.md).
99

1010
For examples see [the pyscript folder](pyscriptjs).
1111

‎docs/Makefile

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
CONDA_ENV ?= _env
11+
12+
# Put it first so that "make" without argument is like "make help".
13+
help:
14+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
15+
16+
env := $(CONDA_ENV)
17+
conda_run := conda run -p $(env)
18+
19+
setup:
20+
@if [ -z "$${CONDA_SHLVL:+x}" ]; then echo "Conda is not installed." && exit 1; fi
21+
$(CONDA_EXE) env $(shell [ -d $(env) ] && echo update || echo create) -p $(env) --file environment.yml
22+
23+
clean:
24+
rm -rf $(BUILDDIR)
25+
26+
clean-all: clean
27+
rm -rf $(env) *.egg-info
28+
29+
shell:
30+
@export CONDA_ENV_PROMPT='<{name}>'
31+
@echo 'conda activate $(env)'
32+
33+
htmlserve:
34+
python -m http.server -d "$(BUILDDIR)/html/"
35+
36+
livehtml:
37+
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
38+
39+
40+
.PHONY: help Makefile setup clean clean-all shell
41+
42+
# Catch-all target: route all unknown targets to Sphinx using the new
43+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
44+
%: Makefile
45+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# PyScript documentation
2+
3+
Welcome to the PyScript documentation directory, where you can find
4+
and contribute to discussions around PyScript and related topics.
5+
6+
## Getting started
7+
8+
Before you start contributing to the documentation, it's worthwhile to
9+
take a look at the general contributing guidelines for the PyScript project.
10+
11+
### Setup
12+
13+
The `docs` directory in the pyscript repository contains a
14+
[Sphinx](https://www.sphinx-doc.org/) documentation project. Sphinx is a system
15+
that takes plaintext files containing documentation written in Markdown, along with
16+
and static files like templates and themes, to build the static end result.

0 commit comments

Comments
 (0)
0