Documentation infrastructure. #262

jezdez · 2022-05-06T15:57:57Z

This does a few things:

Deployment (like ReadTheDocs)

Eventually we need three different types of deployments:

review (pushed to docs.pyscript.net/review/<pr-number>/)
tag (pushed to docs.pyscript.net/<tag>/)
latest (pushed to docs.pyscript.net/latest/)

Refs #167 and #168.

Known issues

the "Edit this page" link is not working on https://docs.pyscript.net/review/262/ since that points to the main branch which doesn't have the files yet, because this PR adds them

README.md

docs/concepts/governance/policy.md

README.md

docs/README.md

idanenglander · 2022-05-06T16:50:22Z

docs/README.md

+The `docs` directory in the pyscript repository contains
+[Sphinx](https://www.sphinx-doc.org/) documentation project, which is a system
+to take a plaintext files containing the documentation written in Markdown
+and static files such as templates and themes to build the static end result.


Minor adjustments. The phrase "such as templates and themes" could alternatively be between commas or parentheses:
The docs directory in the pyscript repository contains the
Sphinx documentation project, a system for publishing static files—such as templates and themes—and plaintext files written in markdown.

Ooh, yes, the em dashes read better.

Did a slightly different rewrite. Let me know what you think once I push my changes.

idanenglander · 2022-05-06T16:56:13Z

docs/concepts/governance/maintainers.md

@@ -0,0 +1,17 @@
+# 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](policy.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.


"represent" isn't really working grammatically here, though I understand the goal of it... perhaps:

"... you authorize the binding of that organization to these policies."

Since @kevingoldsmith put all these governance docs together, I'd like his input on that change before we make it.

represent comes from the original github document. It is meant to be legalese. I wouldn't change it if it is a bit janky but the meaning is clear.

Copy that, thanks Kevin.

docs/tutorials/index.md

kathatherine · 2022-05-06T21:49:51Z

@fpliger @jezdez I also did some general edits and replaced the Lorem Ipsum with some "Coming Soon" text anywhere it was needed. Idan, Albert, and I added some content to the Concepts folder to attempt to give a big picture explanation of PyScript. It still needs work, but is at least mergeable, if y'all are okay with the language.

ximena9201 · 2022-05-11T19:15:14Z

@jezdez I've added some changes in this GHA that puts the docs/ ** content to a S3 public bucket. I guess we still need to automate the releases, tags, or probably make some slightly changes.

cclauss · 2022-05-11T19:44:14Z

LGTM... Nice work. Merge conflict to look into. Py-script is delivering Python 3.10 but several of these GHAs use Py3.9. There might be plenty of good reasons for this dichotomy but it might lead to issues.

There is probably some the thought to be given to "There is no setup" vs. docs/tutorials/setup.md

jezdez · 2022-05-11T20:32:41Z

@jezdez I've added some changes in this GHA that puts the docs/ ** content to a S3 public bucket. I guess we still need to automate the releases, tags, or probably make some slightly changes.

I'll working on that tomorrow if that's okay, thank you for adding those changes!

jezdez · 2022-05-11T20:36:22Z

LGTM... Nice work. Merge conflict to look into. Py-script is delivering Python 3.10 but several of these GHAs use Py3.9. There might be plenty of good reasons for this dichotomy but it might lead to issues.

Good callout, let's fix the Python version difference, no good reason for it IIRC.

There is probably some the thought to be given to "There is no setup" vs. docs/tutorials/setup.md

Huh, fascinating, while I like the messaging of "there is no setup", a tutorial would probably require a user to setup a development environment, to make sure they can actually edit a HTML file and use PyScript. That's worth doing to engage with beginners that will look for ways to start using PyScript. I wonder if we could look at "web development" tutorials out there (MDN?) and get inspiration.

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.

for more information, see https://pre-commit.ci

The existing trigger is apparently not in the GHA spec

for more information, see https://pre-commit.ci

See executablebooks/mdformat-myst#9 for more details.

jezdez · 2022-05-12T17:04:32Z

@fpliger So generally speaking, it would be interesting to understand what would be a good level at which we should do a review and merge of this PR? This is still just a skeleton in terms of content and design, but it might be worth merging to allow smaller content/design PRs to happen.

https://docs.pyscript.net/review/262/ is the current build of this PR (as will all PRs automatically trigger such a review build).

fpliger · 2022-05-12T19:51:13Z

@jezdez totally agree. This became too big of a catch all PR. If you are 👍 I'd say, I can review and merge this and the allow for other smaller (and more digestible) PR to follow. Sounds good to you?

jezdez · 2022-05-13T08:22:27Z

@jezdez totally agree. This became too big of a catch all PR. If you are 👍 I'd say, I can review and merge this and the allow for other smaller (and more digestible) PR to follow. Sounds good to you?

Sounds good to me! Thank you <3

MAINTAINERS.md

kevingoldsmith

generally looks ok, but I'm concerned about making some of the governance documents undiscoverable. I think they make more sense at the project level than buried in the docs. If we want them in the docs we can either reference them at the room, link to them or rephrase them.

kevingoldsmith · 2022-05-15T23:18:10Z

docs/concepts/governance/maintainers.md

@@ -0,0 +1,18 @@
+# Maintainers


I'm not sure we should be burying these files.

I'm +1 on bumping it for governance. In my mind, it's a "special" concept that we want to give big priority.

On a different note, it'd be great if we could link/pull these directly from the governance repo.

Oh, good point @kevingoldsmith, I'll move them back and use a symlink to have the real files in the root of the repo, but also render them on the docs site (we can make a editorial decision if we want to keep them separately).

@fpliger FWIW this structure was recommended by the MVG, to have some files in the project repo, and some on the org level. So if we were to add additional projects to the pyscript organization, they would require also at least a MAINTAINERS.md and GOVERNANCE.md.

fpliger

Wow.. this is an AMAZING starting point!! It'd be +100 on merging this right now.

On a quick chat with @jezdez we agreed that it makes sense to add something like "THIS IS A PLACEHOLDER FOR THE DOCUMENTATION, DO NOT USE IT AS A REFERENCE YET" to the front page until we add meaningful content.

Will merge as soon as it lands :)

fpliger · 2022-05-16T18:39:07Z

docs/concepts/governance/maintainers.md

@@ -0,0 +1,18 @@
+# Maintainers


I'm +1 on bumping it for governance. In my mind, it's a "special" concept that we want to give big priority.

On a different note, it'd be great if we could link/pull these directly from the governance repo.

jezdez · 2022-05-09T14:29:07Z

.github/workflows/docs-release.yml

-    - *
+  # Any time a tag or branch is created
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#create
+    create:


@mattkram You're right, this was written wrong, should have been on: push: tags:

jezdez · 2022-05-16T20:45:47Z

docs/concepts/governance/maintainers.md

@@ -0,0 +1,18 @@
+# Maintainers


Oh, good point @kevingoldsmith, I'll move them back and use a symlink to have the real files in the root of the repo, but also render them on the docs site (we can make a editorial decision if we want to keep them separately).

@fpliger FWIW this structure was recommended by the MVG, to have some files in the project repo, and some on the org level. So if we were to add additional projects to the pyscript organization, they would require also at least a MAINTAINERS.md and GOVERNANCE.md.

jezdez · 2022-05-16T20:46:38Z

docs/conf.py

+# -- Project information -----------------------------------------------------
+
+project = "PyScript"
+copyright = "2022, PyScript contributors"


@kevingoldsmith Is that copyright line correct?

MAINTAINERS.md

jezdez · 2022-05-16T21:11:32Z

docs/concepts/governance/maintainers.md

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


@kevingoldsmith Reverted to just symlink to the root of the repo, while still rendering them in the docs.

jezdez · 2022-05-16T21:43:43Z

@fpliger I've addressed @kevingoldsmith's comments and add the note, does that work?

jezdez · 2022-05-16T21:49:57Z

When the PR is merged, I'll open new issues for the TODO items above left undone. I think the are fine to work on after the fact.

fpliger · 2022-05-17T02:30:10Z

Imo, that works great! I'm +1 on merging this as is and opening issues/PRs for the remaining items /comments (there's a lot of value here that others can build on top of). @kevingoldsmith does that work for you or do you have any reservations?

fpliger · 2022-05-17T17:10:02Z

Thank you for the great work on this @jezdez @ximena9201 @kathatherine @idanenglander and everyone involved!

kathatherine reviewed May 6, 2022

View reviewed changes

README.md Show resolved Hide resolved

docs/concepts/governance/policy.md Outdated Show resolved Hide resolved

idanenglander reviewed May 6, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

idanenglander reviewed May 6, 2022

View reviewed changes

docs/README.md Outdated Show resolved Hide resolved

idanenglander reviewed May 6, 2022

View reviewed changes

docs/tutorials/index.md Outdated Show resolved Hide resolved

marimeireles mentioned this pull request May 10, 2022

pyscript link corrections #285

Closed

cclauss approved these changes May 11, 2022

View reviewed changes

jezdez and others added 17 commits May 12, 2022 13:23

Activate conda env.

07ed619

Remove custom action.

00ffc76

[pre-commit.ci] auto fixes from pre-commit.com hooks

6bce7ad

for more information, see https://pre-commit.ci

Make the dir.

e6a48f7

Push directly

fb4b94d

Add readthedocs config.

d8b6be5

Disable GitHub pages deployment for now.

448fd17

Add release and latest workflows as well.

200b8da

Make clear that this is work in progress.

16450c5

Made docs merge ready, added What is PyScript section with example.

8cbdbd7

[pre-commit.ci] auto fixes from pre-commit.com hooks

e96ce92

for more information, see https://pre-commit.ci

Replace on:tags: with on:create:

c21fe3b

The existing trigger is apparently not in the GHA spec

Pretty format YAML

485bfdd

[pre-commit.ci] auto fixes from pre-commit.com hooks

7cbcde4

for more information, see https://pre-commit.ci

add s3 sync and permissions

8599cbb

Leave status message in PR.

3eccb20

jezdez added 6 commits May 12, 2022 16:53

Move to sphinx-design.

38c2e12

Add sphinx-autobuild.

c8174b7

Use frontmatter more.

380cc6d

Add section for mdformat but disable it for now.

fce1741

See executablebooks/mdformat-myst#9 for more details.

Fix fencing.

02a95a6

Actually using html renderer.

110d52d

kevingoldsmith reviewed May 15, 2022

View reviewed changes

MAINTAINERS.md Show resolved Hide resolved

kevingoldsmith suggested changes May 15, 2022

View reviewed changes

fpliger approved these changes May 16, 2022

View reviewed changes

jezdez commented May 16, 2022

View reviewed changes

jezdez added 2 commits May 16, 2022 22:54

Revert moving governance files.

53ed279

Use full URLs for governance docs.

2a5c08e

jezdez added the tag: docs Related to the documentation label May 16, 2022

jezdez commented May 16, 2022

View reviewed changes

jezdez added 3 commits May 16, 2022 23:27

Added warning.

bdbd2ab

Fix copyright and author.

840f296

Another minor fix.

e1c78c4

Use GitHub Action summary instead of notice.

2faa6f3

jezdez self-assigned this May 17, 2022

Fix variable name.

1171275

fpliger merged commit 6898daf into main May 17, 2022

fpliger deleted the docs-infra branch May 17, 2022 17:08

jezdez mentioned this pull request May 20, 2022

Next-gen documentation infrastructure conda/conda-docs#777

Closed

9 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation infrastructure. #262

Documentation infrastructure. #262

jezdez commented May 6, 2022 •

edited by idanenglander

idanenglander May 6, 2022

kathatherine May 6, 2022

kathatherine May 6, 2022

idanenglander May 6, 2022

kathatherine May 6, 2022

kevingoldsmith May 15, 2022

idanenglander May 16, 2022

kathatherine commented May 6, 2022

ximena9201 commented May 11, 2022

cclauss commented May 11, 2022

jezdez commented May 11, 2022

jezdez commented May 11, 2022

jezdez commented May 12, 2022

fpliger commented May 12, 2022

jezdez commented May 13, 2022

kevingoldsmith left a comment

kevingoldsmith May 15, 2022

fpliger May 16, 2022

jezdez May 16, 2022

fpliger left a comment

fpliger May 16, 2022

jezdez May 9, 2022

jezdez May 16, 2022

jezdez May 16, 2022

jezdez May 16, 2022

jezdez commented May 16, 2022

jezdez commented May 16, 2022

fpliger commented May 17, 2022

fpliger commented May 17, 2022

		@@ -0,0 +1,17 @@
		# 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](policy.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.

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

Documentation infrastructure. #262

Documentation infrastructure. #262

Conversation

jezdez commented May 6, 2022 • edited by idanenglander

Deployment (like ReadTheDocs)

Known issues

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kathatherine commented May 6, 2022

ximena9201 commented May 11, 2022

cclauss commented May 11, 2022

jezdez commented May 11, 2022

jezdez commented May 11, 2022

jezdez commented May 12, 2022

fpliger commented May 12, 2022

jezdez commented May 13, 2022

kevingoldsmith left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fpliger left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jezdez commented May 16, 2022

jezdez commented May 16, 2022

fpliger commented May 17, 2022

fpliger commented May 17, 2022

jezdez commented May 6, 2022 •

edited by idanenglander