01 Proper Package: Finish cleanup and copy over the Markdown for the first DDD step.

pauleveritt · pauleveritt · commit 7661f70f512a · 2022-09-11T15:26:23.000-04:00
diff --git a/.darglint b/.darglint
@@ -0,0 +1,2 @@
+[darglint]
+strictness = long
diff --git a/.flake8 b/.flake8
@@ -0,0 +1,11 @@
+[flake8]
+select = B,B9,C,D,DAR,E,F,N,RST,S,W
+ignore = E203,E501,RST201,RST203,RST301,W503,B008
+max-line-length = 80
+max-complexity = 10
+docstring-convention = google
+per-file-ignores =
+    tests/*:S101
+    src/psc/static/pyscript.py:D100,D101,D102,D103,D107,D200,D212,D415,N802,N806
+rst-roles = class,const,func,meth,mod,ref
+rst-directives = deprecated
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1 @@
+* text=auto eol=lf
diff --git a/.gitignore b/.gitignore
@@ -136,3 +136,8 @@ dmypy.json
 .pyre/
 
 node_modules/
+
+.idea
+/.nox/
+/dist/
+/docs/_build/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,66 @@
+repos:
+  - repo: local
+    hooks:
+      - id: black
+        name: black
+        entry: black
+        language: system
+        types: [python]
+        require_serial: true
+      - id: check-added-large-files
+        name: Check for added large files
+        entry: check-added-large-files
+        language: system
+      - id: check-toml
+        name: Check Toml
+        entry: check-toml
+        language: system
+        types: [toml]
+      - id: check-yaml
+        name: Check Yaml
+        entry: check-yaml
+        language: system
+        types: [yaml]
+      - id: darglint
+        name: darglint
+        entry: darglint
+        language: system
+        types: [python]
+        stages: [manual]
+      - id: end-of-file-fixer
+        name: Fix End of Files
+        entry: end-of-file-fixer
+        language: system
+        types: [text]
+        stages: [commit, push, manual]
+      - id: flake8
+        name: flake8
+        entry: flake8
+        language: system
+        types: [python]
+        require_serial: true
+        args: [--darglint-ignore-regex, .*]
+      - id: isort
+        name: isort
+        entry: isort
+        require_serial: true
+        language: system
+        types_or: [cython, pyi, python]
+        args: ["--filter-files"]
+      - id: pyupgrade
+        name: pyupgrade
+        description: Automatically upgrade syntax for newer versions.
+        entry: pyupgrade
+        language: system
+        types: [python]
+        args: [--py37-plus]
+      - id: trailing-whitespace
+        name: Trim Trailing Whitespace
+        entry: trailing-whitespace-fixer
+        language: system
+        types: [text]
+        stages: [commit, push, manual]
+#  - repo: https://github.com/pre-commit/mirrors-prettier
+#    rev: v2.6.0
+#    hooks:
+#      - id: prettier
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,12 @@
+version: 2
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
+sphinx:
+  configuration: docs/conf.py
+formats: all
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - path: .
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,4 @@
+# Code of Conduct
+
+The Code of Conduct is available in [the PyScript Governance repo](https://github.com/pyscript/governance/blob/main/CODE-OF-CONDUCT.md).
+See https://github.com/pyscript/governance/blob/main/CODE-OF-CONDUCT.md
diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD
@@ -30,8 +30,10 @@ We try not to have strong boundaries in what kinds of contributions are accepted
 
 - Adding meta-data
 
-  - adding tags to your example will help us organize this repository in a much more meaningful way. Example tags come at the beginning of your main `HTML` file in the form of a comment. See the [example](examples/hello_world.html)
-  - you're also welcome to add your email or name or other forms of contact information in the header at the beginning of the file. See the [example](examples/hello_world.html)
+  - adding tags to your example will help us organize this repository in a much more meaningful way. Example tags come at the beginning of your main `HTML` file in the form of a comment.
+  - you're also welcome to add your email or name or other forms of contact information in the header at the beginning of the file.
+
+TODO Add back in `See the example  examples/hello_world.html`
 
 - Adding docs
 
@@ -52,7 +54,7 @@ The PyScript Collective also welcomes contributions like blog posts, videos, vid
 
 The contributions in this topic are more similar to what an `awesome-page` would look like.
 
-*If you want to add a new kind of contribution that wasn't laid out on the [README](README.md) yet, feel free to do so.*
+*If you want to add a new kind of contribution that wasn't laid out on the [README](index) yet, feel free to do so.*
 
 #### Recommended guidelines for a resource
 
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ We strive to make people feel valued and valuable and we hope to make lots of it
 
 ## Index
 
-[Examples]()
+TODO Link to Examples
 
 ## Resources
 
@@ -15,3 +15,8 @@ We strive to make people feel valued and valuable and we hope to make lots of it
 * [Discussion Board](https://community.anaconda.cloud/c/tech-topics/pyscript)
 * [Blog Post](https://engineering.anaconda.com/2022/04/welcome-pyscript.html)
 * [Stack Overflow](https://stackoverflow.com/questions/tagged/PyScript)
+
+<!-- github-only -->
+
+[license]: https://github.com/pyscript/pyscript-collective/blob/main/LICENSE
+[contributor guide]: https://github.com/pyscript/pyscript-collective/blob/main/CONTRIBUTING.md
diff --git a/codecov.yaml b/codecov.yaml
@@ -0,0 +1,9 @@
+comment: false
+coverage:
+  status:
+    project:
+      default:
+        target: "100"
+    patch:
+      default:
+        target: "100"
diff --git a/docs/building/index.md b/docs/building/index.md
@@ -0,0 +1,30 @@
+# Building the Collective
+
+The Pyscript Collective is about people helping people, but it also produces 3 software artifacts:
+
+- Well-maintained example apps
+- A website
+- An installable package to locally run (and tinker with) the examples
+
+These docs describe the writing of the repository for this software.
+It's done as "Diary Driven Development": one step at a time, describe the "why", then explain the what.
+
+At each step:
+
+- Work on the branch
+- Write docs for the problem being solved
+- Notes on the solution
+- Open questions
+- Make a commit that clearly identifies the step.
+
+You can then "follow along" so to speak by looking at each commit.
+This section covers each step in the prototype.
+
+```{toctree}
+---
+hidden:
+maxdepth: 1
+---
+
+proper_package
+```
diff --git a/docs/building/proper_package.md b/docs/building/proper_package.md
@@ -0,0 +1,67 @@
+# Proper Package
+
+This PSC isn't just prototyping examples to list on a webpage.
+It's actually an installable Python package, making it easy for people to _consume and tinker with_ the examples.
+
+As such, PSC starts with a clean-slate:
+
+- Updated from (controversially) the [Hypermodern Python cookiecutter](https://cookiecutter-hypermodern-python.readthedocs.io/en/latest/index.html)
+- An installable package on PyPI
+- A full Collective documentation site based on Sphinx
+
+Let's look at each decision in detail.
+
+## Hypermodern Cookiecutter
+
+This effort builds the Collective atop a Hypermodern cookiecutter package.
+Meaning: Poetry, pytest, pre-commit, mypy, nox, GitHub actions, Sphinx, and other Python tooling.
+
+Admittedly, this is an *aggressive* decision.
+The reasoning:
+
+- We want the Collective to be good examples of Python coding
+- Extra work to make them easy to learn
+- Since the Collective will assume the maintenance, extra work on tests, quality, and standards.
+
+We acknowledge that this raises the bar for contribution.
+(We can turn off some knobs to be less strict.)
+It is likely that we do the work to convert a PR into a passing contribution.
+
+## Installable Package
+
+As part of the Collective reboot, it's written as if it is a Python package, meant to be installed.
+This will potentially make it dead-simple for people to play with the examples, even to edit them and see results.
+They will just `pip install our-package` and get everything needed.
+Or even simpler, use `pipx` to just run the examples.
+
+:::{attention} Package name?
+The PyScript ecosystem should adopt a prefix for add-on packages, as done in Django, Flask, Pyramid, etc.
+Presumably this package will be named `pyscript-collective`.
+
+That's pretty long, though.
+Perhaps PyScript should adopt `ps-` as the prefix?
+With the Collective adopting `psc-` for a prefix?
+:::
+
+## Conda -> Poetry
+
+The existing `pyscript-collective` repo starts with a `Makefile`.
+It also presumes Conda for everything.
+
+This effort switches over to Poetry for contributors and pip for consumers.
+The use of Poetry isn't important -- we could easily switch to `virtualenv` and `requirements.txt`.
+But the switch away from Conda is more intentional: it's less used per the PSF survey, and we want to show that PyScript isn't tied to Anaconda nor Conda.
+
+## Docs in Sphinx
+
+This Collective repo will need documentation for contributors, maintainers and others.
+
+:::{note} Docs, not website
+Just to be clear, this section describes the *docs* for the Collective, not the *website* and web app that are ultimately created.
+:::
+
+The Hypermodern Sphinx setup does an include of Markdown files stored in the repo root: README, Code of Conduct, license, etc.
+Those needed some fixing to be MyST compliant.
+For example, we edited the Sphinx `conf.py` file to enable MyST [autogenerate headers](https://myst-parser.readthedocs.io/en/v0.17.1/syntax/optional.html#syntax-header-anchors) to make the README internal links happy.
+
+We also copied over the Code of Conduct text from the PyScript repo.
diff --git a/docs/codeofconduct.md b/docs/codeofconduct.md
@@ -0,0 +1,3 @@
+```{include} ../CODE_OF_CONDUCT.md
+
+```
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,13 @@
+"""Sphinx configuration."""
+project = "PyScript Collective"
+author = "PyScript Collective"
+copyright = "2022, PyScript"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_click",
+    "myst_parser",
+]
+autodoc_typehints = "description"
+html_theme = "furo"
+myst_heading_anchors = 4
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,2 @@
+```{include} ../CONTRIBUTING.md
+```
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,21 @@
+```{include} ../README.md
+---
+end-before: <!-- github-only -->
+---
+```
+
+[license]: license
+[contributor guide]: contributing
+
+```{toctree}
+---
+hidden:
+maxdepth: 1
+---
+
+contributing
+building/index
+Code of Conduct <codeofconduct>
+License <license>
+Changelog <https://github.com/pyscript/pyscript-collective/releases>
+```
diff --git a/docs/license.md b/docs/license.md
@@ -0,0 +1,7 @@
+# License
+
+```{literalinclude} ../LICENSE.md
+---
+language: none
+---
+```
diff --git a/examples/hello_world.html b/examples/hello_world.html
@@ -1,4 +1,4 @@
-<!-- 
+<!--
   contributor: example@contributor.me
   tags: example-tag, another-example
 -->
diff --git a/noxfile.py b/noxfile.py
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/src/psc/__init__.py b/src/psc/__init__.py
diff --git a/tests/__init__.py b/tests/__init__.py
diff --git a/tests/conftest.py b/tests/conftest.py
diff --git a/tests/test_examples.py b/tests/test_examples.py
