Minimal steps to add a website

[choldgraf]

This is another implementation PR of #29 - it makes minimal changes needed to get a Jupyter Book building a website from the JEPs that are here. It also does some minor re-configuration of metadata, titles, etc to make it easier to organize and parse.

It also adds a github action that will automatically build the book and push to github-pages, and the docs will be publicly available at https://jupyter.org/enhancement-proposals

Note: there are probably other things to improve here, but I wanted to take the minimal number of steps and we can always iterate in the future if people like it

Here's how it looks:

https://2-41511140-gh.circle-artifacts.com/0/html/README.html

[blink1073]

LGTM, thanks!

[bollwyvl]

This is looking great!

Standardizing the YAML front matter is fantastic. I think, to that end, I would love to see pushing further on the structured data approach:

• formalize the as-used frontmatter as required fields in a JSON schema
  • go ahead and store it in the front-matter of jep-29!
    • i could, in fact, see this becoming a useful way to really normalize our use of schema across the ecosystem, rather than having reference implementations own them
  • normalize some things to be more data-ful than string-y
    • authors as a list
• validate incoming JEPs against the schema in CI

A notional schema for what I see thus far:

title: Jupyter Extension Proposal (JEP) Front Matter
description: minimum JEP information for automated reviewing and publishing
$id: https://github.com/jupyter/extension-propsals/tree/master/29-jep-process/jep-process.md
$schema: http://json-schema.org/draft-07/schema#
type: object

required:
  - authors
  - date-started
  - issue-number
  - pr-number
  - title
  - type

definitions:
  authors:
    type: array
    items:
      type: string
    minItems: 1

  title:
    type: string

  issue-number:
    type: number

  pr-number:
    type: number

  date-started:
    type: string
    format: date

  type:
    description: see https://www.python.org/dev/peps/#pep-types-key
    type: string
    enum:
      - S - Standards Track
      - I - Informational
      - P - Process

Speaking of CI: wonderful! Perhaps we can we apply some additional checks to in-coming (and current) documents as well:

• pytest-check-links against the generated website
• spelling?
  • the hunspell workflow works well against HTML
  • maintaining a (sorted) dictionary.txt is somewhat cantankerous, but worth it in the long-run
    • kept organized, it actually helps highlight what are a project's "special" terms, and aids in normalizing terms of art, e.g. JupyterHub and Jupyterhub which are boring typos to have to comment on in review and fix
• auto-formatting?
  • prettier is probably the strongest game in town
  • a lot of people don't like having their markdown formatted, but I've found it really helps in the long-term maintainability of a collection long documents.
  • prose-wrap
  • since few will probably actually install the full build toolchain, a linter action could propose the delta back to the PR

[choldgraf]

@bollwyvl I think both of your ideas are worth pushing on in separate issues - wanna open them up and we can discuss? I am happy to keep putting cycles into improving these docs (though suspect adopting a formal spec may need a JEP of its own?)

[choldgraf]

wohoo, it's live: https://jupyter.org/enhancement-proposals