Before you start contributing to the documentation, it's worthwhile to take a look at the general contributing guidelines for the PyScript project. You can find these guidelines here Contributing Guidelines

Documentation Principles

The PyScript documentation is based on a documentation framework called Diátaxis. This framework helps to solve the problem of structure in technical documentation and identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. Each one of these modes answers to a different user need, fulfills a different purpose and requires a different approach to its creation.

The picture below gives a good visual representation of that separation of concerns:

So, please keep that in mind when contributing to the project documentation. For more information on, make sure to check their website.

Setup

The docs directory in the pyscript repository contains a Material for MkDocs documentation project. Material is a system that takes plaintext files containing documentation written in Markdown, along with static files like templates and themes, to build the static end result.

To setup the documentation development environment simply run make setup from this folder and, once it's done, activate your environment by running conda activate ./_env

Build

Simply run mkdocs serve

Cross-referencing

You can link to other pages in the documentation by using the {doc} role. For example, to link to the docs/README.md file, you would use:

{doc}`docs/README.md`

You can also cross-reference the python glossary by using the {term} role. For example, to link to the iterable term, you would use:

{term}`iterable`

You can also cross-reference functions, methods or data attributes by using the {attr} for example:

{py:func}`repr`

This would link to the repr function in the python builtins.