Add User Guide and improve documentation

Our README currently provides the bare bare minimum information to get onboarded with PyScript (arguably below minimum 😃. We need a real user guide/user documentation. Hope we can use this issue to capture the major sections of the user guide as well as the qualities that we want to prioritize for when creating it. PRs can come out of this issue or, eventually, we can generate new issues out of this one.

NOTE: The following work can be split in multiple PRs and even smaller issues.

Principles

Every part of the documentation should keep in mind the vision of the project in mind: programming for the 99%. So we should check that any addition aligns to the following principles:

• accessibility
• inclusiveness
• simplicity

Main Sections

• Introduction/Description: what is PyScript, the goals, what PyScript is not, etc…
• Getting started: this should be really simple and short 😃. Should show hot so include PyScript in a page and how to have a simple <py-script> snipped running
• How to use it: this should be the continuation from the “getting started” sections and should show mode details on each component that can be added in PyScript:

Update: these are solved:

• <py-env>
• <py-script>
• <py-repl>
• Visual Components
  • <py-inputbox>
  • <py-box>
  • <py-button>
  • <py-list>
  • <py-title>

These are still TBD:

• Advanced:
  • understanding how PyScript works
  • registering your own PyScript components
  • components API
• Best practices: focusing a serious of things to do/account for when working with PyScript to have the optimal performance/experince possible (i.e: browser versions, etc…)

Ideas very welcome in the comments.

[jezdez]

I’d would strongly suggest to follow the Diátaxis Framework in how to structure the docs to guide different levels of experience to the right place. This has been a pattern that was successfully applied to many different OSS projects and should be a good starting point to build out.

[fpliger]

@marimeireles do you mind checking the docs vs the items in the descriptions and open issues of the ones missing so we can encourage granular contributions and close this issue?