From 408c49f95196c19a1ed9d3ca3661a9cb494b722c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Fri, 23 Aug 2024 14:25:29 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docs=20references=20to=20F?= =?UTF-8?q?astAPI's=20docs=20on=20virtual=20environments=20and=20new=20con?= =?UTF-8?q?tributing=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contributing.md | 164 +++++++++++++++++++++++++++++++++++++++ docs/tutorial/install.md | 17 ++++ mkdocs.yml | 2 + 3 files changed, 183 insertions(+) create mode 100644 docs/contributing.md create mode 100644 docs/tutorial/install.md diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..2daef2a --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,164 @@ +# Contributing + +First, you might want to see the basic ways to [help Asyncer and get help](help.md){.internal-link target=_blank}. + +## Developing + +If you already cloned the asyncer repository and you want to deep dive in the code, here are some guidelines to set up your environment. + +### Virtual Environment + +Follow the instructions to create and activate a virtual environment as described in the FastAPI page on Virtual Environments for the internal code of `asyncer`. + +### Install Requirements Using `pip` + +After activating the environment, install the required packages: + +
+ +```console +$ pip install -r requirements.txt + +---> 100% +``` + +
+ +It will install all the dependencies and your local Asyncer in your local environment. + +### Using your Local Asyncer + +If you create a Python file that imports and uses Asyncer, and run it with the Python from your local environment, it will use your cloned local Asyncer source code. + +And if you update that local Asyncer source code when you run that Python file again, it will use the fresh version of Asyncer you just edited. + +That way, you don't have to "install" your local version to be able to test every change. + +/// note | "Technical Details" + +This only happens when you install using this included `requirements.txt` instead of running `pip install asyncer` directly. + +That is because inside the `requirements.txt` file, the local version of Asyncer is marked to be installed in "editable" mode, with the `-e` option. + +/// + +### Format + +There is a script that you can run that will format and clean all your code: + +
+ +```console +$ bash scripts/format.sh +``` + +
+ +It will also auto-sort all your imports. + +## Tests + +There is a script that you can run locally to test all the code and generate coverage reports in HTML: + +
+ +```console +$ bash scripts/test.sh +``` + +
+ +This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing. + +## Docs + +First, make sure you set up your environment as described above, that will install all the requirements. + +### Docs Live + +During local development, there is a script that builds the site and checks for any changes, live-reloading: + +
+ +```console +$ python ./scripts/docs.py live + +[INFO] Serving on http://127.0.0.1:8008 +[INFO] Start watching changes +[INFO] Start detecting changes +``` + +
+ +It will serve the documentation on `http://127.0.0.1:8008`. + +That way, you can edit the documentation/source files and see the changes live. + +/// tip + +Alternatively, you can perform the same steps that scripts does manually. + +Go into the docs director at `docs/`: + +```console +$ cd docs/ +``` + +Then run `mkdocs` in that directory: + +```console +$ mkdocs serve --dev-addr 8008 +``` + +/// + +#### Typer CLI (Optional) + +The instructions here show you how to use the script at `./scripts/docs.py` with the `python` program directly. + +But you can also use Typer CLI, and you will get autocompletion in your terminal for the commands after installing completion. + +If you install Typer CLI, you can install completion with: + +
+ +```console +$ typer --install-completion + +zsh completion installed in /home/user/.bashrc. +Completion will take effect once you restart the terminal. +``` + +
+ +### Docs Structure + +The documentation uses MkDocs. + +And there are extra tools/scripts in place in `./scripts/docs.py`. + +/// tip + +You don't need to see the code in `./scripts/docs.py`, you just use it in the command line. + +/// + +All the documentation is in Markdown format in the directory `./docs`. + +Many of the tutorials have blocks of code. + +In most of the cases, these blocks of code are actual complete applications that can be run as is. + +In fact, those blocks of code are not written inside the Markdown, they are Python files in the `./docs_src/` directory. + +And those Python files are included/injected in the documentation when generating the site. + +### Docs for Tests + +Most of the tests actually run against the example source files in the documentation. + +This helps to make sure that: + +* The documentation is up-to-date. +* The documentation examples can be run as is. +* Most of the features are covered by the documentation, ensured by test coverage. diff --git a/docs/tutorial/install.md b/docs/tutorial/install.md new file mode 100644 index 0000000..12783d9 --- /dev/null +++ b/docs/tutorial/install.md @@ -0,0 +1,17 @@ +# Install + +Before starting, create a project directory, and then create a **virtual environment** in it to install the packages. + +You can read the FastAPI page on Virtual Environments. + +Then activate the virtual environment, and then install Asyncer, for example: + +
+ +```console +$ pip install asyncer +---> 100% +Successfully installed asyncer anyio +``` + +
diff --git a/mkdocs.yml b/mkdocs.yml index 7f6afb0..36a6384 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,6 +66,7 @@ nav: - Asyncer: index.md - Tutorial - User Guide: - tutorial/index.md + - tutorial/install.md - tutorial/first-steps.md - tutorial/runnify.md - tutorial/soonify.md @@ -76,6 +77,7 @@ nav: - Resources: - resources/index.md - help.md + - contributing.md - management-tasks.md - About: - about/index.md