📝 Add docs references to FastAPI's docs on virtual environments and new contributing guide (#200)

Author: tiangolo

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 <a href="https://github.com/fastapi/asyncer" class="external-link" target="_blank">asyncer repository</a> 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 <a href="https://fastapi.tiangolo.com/virtual-environments/" class="external-link" target="_blank">FastAPI page on Virtual Environments</a> for the internal code of `asyncer`.
+
+### Install Requirements Using `pip`
+
+After activating the environment, install the required packages:
+
+<div class="termy">
+
+```console
+$ pip install -r requirements.txt
+
+---> 100%
+```
+
+</div>
+
+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:
+
+<div class="termy">
+
+```console
+$ bash scripts/format.sh
+```
+
+</div>
+
+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:
+
+<div class="termy">
+
+```console
+$ bash scripts/test.sh
+```
+
+</div>
+
+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:
+
+<div class="termy">
+
+```console
+$ python ./scripts/docs.py live
+
+<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
+<span style="color: green;">[INFO]</span> Start watching changes
+<span style="color: green;">[INFO]</span> Start detecting changes
+```
+
+</div>
+
+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 <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>, and you will get autocompletion in your terminal for the commands after installing completion.
+
+If you install Typer CLI, you can install completion with:
+
+<div class="termy">
+
+```console
+$ typer --install-completion
+
+zsh completion installed in /home/user/.bashrc.
+Completion will take effect once you restart the terminal.
+```
+
+</div>
+
+### Docs Structure
+
+The documentation uses <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
+
+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.

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 <a href="https://fastapi.tiangolo.com/virtual-environments/" class="external-link" target="_blank">FastAPI page on Virtual Environments</a>.
+
+Then activate the virtual environment, and then install Asyncer, for example:
+
+<div class="termy">
+
+```console
+$ pip install asyncer
+---> 100%
+Successfully installed asyncer anyio
+```
+
+</div>

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