📝 Add first version of docs

Author: tiangolo

docs/alternatives.md

@@ -0,0 +1,125 @@
+First, you might want to see the basic ways to <a href="https://typer.tiangolo.com/help-typer/" target="_blank">help Typer and get help</a>.
+
+Coming soon...
+
+<!-- ## Developing
+
+If you already cloned the repository and you know that you need to deep dive in the code, here are some guidelines to set up your environment.
+
+
+### Pipenv
+
+If you are using <a href="https://pipenv.readthedocs.io/en/latest/" target="_blank">Pipenv</a>, you can create a virtual environment and install the packages with:
+
+```bash
+pipenv install --dev
+```
+
+Then you can activate that virtual environment with:
+
+```bash
+pipenv shell
+```
+
+
+### No Pipenv
+
+If you are not using Pipenv, you can create a virtual environment with your preferred tool, and install the packages listed in the file `Pipfile`.
+
+
+### Flit
+
+**FastAPI** uses <a href="https://flit.readthedocs.io/en/latest/index.html" target="_blank">Flit</a> to build, package and publish the project.
+
+If you installed the development dependencies with one of the methods above, you already have the `flit` command.
+
+To install your local version of FastAPI as a package in your local environment, run:
+
+```bash
+flit install --symlink
+```
+
+It will install your local FastAPI in your local environment.
+
+
+#### Using your local FastAPI
+
+If you create a Python file that imports and uses FastAPI, and run it with the Python from your local environment, it will use your local FastAPI source code.
+
+And if you update that local FastAPI source code, as it is installed with `--symlink`, when you run that Python file again, it will use the fresh version of FastAPI you just edited.
+
+That way, you don't have to "install" your local version to be able to test every change.
+
+
+### Format
+
+There is a script that you can run that will format and clean all your code:
+
+```bash
+bash scripts/lint.sh
+```
+
+It will also auto-sort all your imports.
+
+For it to sort them correctly, you need to have FastAPI installed locally in your environment, with the command in the section above:
+
+```bash
+flit install --symlink
+```
+
+
+### Docs
+
+The documentation uses <a href="https://www.mkdocs.org/" target="_blank">MkDocs</a>.
+
+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 making 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 the coverage tests.
+
+During local development, there is a script that builds the site and checks for any changes, live-reloading:
+
+```bash
+bash scripts/docs-live.sh
+```
+
+It will serve the documentation on `http://0.0.0.0:8008`.
+
+That way, you can edit the documentation/source files and see the changes live.
+
+#### Apps and docs at the same time
+
+And if you run the examples with, e.g.:
+
+```bash
+uvicorn tutorial001:app --reload
+```
+
+as Uvicorn by default will use the port `8000`, the documentation on port `8008` won't clash.
+
+
+### Tests
+
+There is a script that you can run locally to test all the code and generate coverage reports in HTML:
+
+```bash
+bash scripts/test-cov-html.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/contributing.md

@@ -0,0 +1,74 @@
+## Design based on **FastAPI**
+
+**Typer** is the little sibling of <a href="https://fastapi.tiangolo.com" target="_blank">FastAPI</a>.
+
+It follows the same design and ideas. If you know FastAPI, you already know **Typer**... more or less.
+
+## Just Modern Python
+
+It's all based on standard **Python 3.6 type** declarations. No new syntax to learn. Just standard modern Python.
+
+If you need a 2 minute refresher of how to use Python types (even if you don't use FastAPI or Typer), check the FastAPI tutorial section: <a href="https://fastapi.tiangolo.com/python-types/" target="_blank">Python types intro</a>.
+
+You will also see a 20 seconds refresher on the section [Tutorial - User Guide: First Steps](tutorial/first-steps.md).
+
+## Editor support
+
+**Typer** was designed to be easy and intuitive to use, to ensure the best development experience. With autocompletion everywhere.
+
+You will rarely need to come back to the docs.
+
+Here's how your editor might help you:
+
+* in <a href="https://code.visualstudio.com/" target="_blank">Visual Studio Code</a>:
+
+![editor support](img/vscode-completion.png)
+
+* in <a href="https://www.jetbrains.com/pycharm/" target="_blank">PyCharm</a>:
+
+![editor support](img/pycharm-completion.png)
+
+You will get completion for everything. That's something no other CLI library provides right now.
+
+No more guessing what type was that variable, if it could be `None`, etc.
+
+### Short
+
+It has sensible **defaults** for everything, with optional configurations everywhere. All the parameters can be fine-tuned to do what you need, customize the help, callbacks per parameter, make them required or not, etc.
+
+But by default, it all **"just works"**.
+
+## User friendly CLI apps
+
+The resulting CLI apps created with **Typer** have the nice features of many "pro" command line programs you probably already love.
+
+* Automatic help commands and options.
+* Automatic command and sub-command structure handling (you will see more about sub-commands in the Tutorial - User Guide).
+* Automatic autocompletion for the CLI app in all operating systems, in all the shells (Bash, Zsh, Fish, PowerShell), so that the final user of your app can just hit <kbd>TAB</kbd> and get the options of sub-commands. *
+
+!!! note * Autocompletion
+    For the autocompletion to work on all shells you also need to add the dependency `click-completion`.
+
+    Just that. And **Typer** does the rest.
+    
+    If **Typer** detects `click-completion` installed, it will automatically create a command to install completion for the user's shell.
+
+    Then you can tell the user to run that command and the rest will just work.
+
+## The power of Click
+
+<a href="https://click.palletsprojects.com" target="_blank">Click</a> is one of the most popular tools for building CLIs in Python.
+
+**Typer** is based on it, so you get all its benefits, plug-ins, robustness, etc.
+
+But you can write simpler code with the benefits of modern Python.
+
+<!-- 
+
+TODO
+
+### Tested
+
+* 100% <abbr title="The amount of code that is automatically tested">test coverage</abbr>.
+* 100% <abbr title="Python type annotations, with this your editor and external tools can give you better support">type annotated</abbr> code base.
+* Used in production applications. -->

docs/features.md

@@ -0,0 +1,92 @@
+Are you liking **Typer**?
+
+Would you like to help Typer, other users, and the author?
+
+Or would you like to get help with **Typer**?
+
+There are very simple ways to help (several involve just one or two clicks).
+
+And there are several ways to get help too.
+
+## Star **Typer** in GitHub
+
+You can "star" Typer in GitHub (clicking the star button at the top right): <a href="https://github.com/tiangolo/typer" target="_blank">https://github.com/tiangolo/typer</a>.
+
+By adding a star, other users will be able to find it more easily and see that it has been already useful for others.
+
+## Watch the GitHub repository for releases
+
+You can "watch" Typer in GitHub (clicking the "watch" button at the top right): <a href="https://github.com/tiangolo/typer" target="_blank">https://github.com/tiangolo/typer</a>.
+
+There you can select "Releases only".
+
+Doing it, you will receive notifications (in your email) whenever there's a new release (a new version) of **Typer** with bug fixes and new features.
+
+## Connect with the author
+
+You can connect with <a href="https://tiangolo.com" target="_blank">me (Sebastián Ramírez / `tiangolo`)</a>, the author.
+
+You can:
+
+* <a href="https://github.com/tiangolo" target="_blank">Follow me on **GitHub**</a>.
+    * See other Open Source projects I have created that could help you.
+    * Follow me to see when I create a new Open Source project.
+* <a href="https://twitter.com/tiangolo" target="_blank">Follow me on **Twitter**</a>.
+    * Tell me how you use Typer (I love to hear that).
+    * Ask questions.
+* <a href="https://www.linkedin.com/in/tiangolo/" target="_blank">Connect with me on **Linkedin**</a>.
+    * Talk to me.
+    * Endorse me or recommend me :)
+* Read what I write (or follow me):
+    * Read other ideas, articles and tools I have created.
+    * Follow me to see when I publish something new.
+    * On <a href="https://dev.to/tiangolo" target="_blank">**Dev.to**</a>.
+    * On <a href="https://medium.com/@tiangolo" target="_blank">**Medium**</a>.
+
+## Tweet about **Typer**
+
+<a href="http://twitter.com/home/?status=I'm loving Typer because... https://github.com/tiangolo/typer cc @tiangolo" target="_blank">Tweet about **Typer**</a> and let me and others know why you like it.
+
+## Let me know how are you using **Typer**
+
+I love to hear about how **Typer** is being used, what have you liked in it, in which project/company you are using it, etc.
+
+You can let me know:
+
+* <a href="http://twitter.com/home/?status=Hey @tiangolo, I'm using Typer at..." target="_blank">On **Twitter**</a>.
+* <a href="https://www.linkedin.com/in/tiangolo/" target="_blank">On **Linkedin**</a>.
+* <a href="https://dev.to/tiangolo" target="_blank">On **Dev.to**</a>.
+* <a href="https://medium.com/@tiangolo" target="_blank">On **Medium**</a>.
+
+## Help others with issues in GitHub
+
+You can see <a href="https://github.com/tiangolo/typer/issues" target="_blank">existing issues</a> and try and help others.
+
+## Watch the GitHub repository
+
+You can "watch" Typer in GitHub (clicking the "watch" button at the top right): <a href="https://github.com/tiangolo/typer" target="_blank">https://github.com/tiangolo/typer</a>.
+
+If you select "Watching" instead of "Releases only", you will receive notifications when someone creates a new issue.
+
+Then you can try and help them solving those issues.
+
+## Create issues
+
+You can <a href="https://github.com/tiangolo/typer/issues/new/choose" target="_blank">create a new issue</a> in the GitHub repository, for example to:
+
+* Report a bug/issue.
+* Suggest a new feature.
+* Ask a question.
+
+## Create a Pull Request
+
+You can <a href="https://github.com/tiangolo/typer" target="_blank">create a Pull Request</a>, for example:
+
+* To fix a typo you found on the documentation.
+* To propose new documentation sections.
+* To fix an existing issue/bug.
+* To add a new feature.
+
+---
+
+Thanks!