Add dedicated installation guide (#97)

* Add dedicated installation guide to docs

* Improve and tweak docs in a few places

Author: lagru

README.md

@@ -15,7 +15,7 @@ It does so by supporting widely used readable conventions such as `array of dtyp
 
 ## Installation & getting started
 
-Please refer to the [introduction](https://docstub.readthedocs.io/en/latest/introduction.html) to get started with docstub.
+Please refer to the installation guide and introduction in our [official documentation](https://docstub.readthedocs.io/) or in [docs/](docs/) to get started.
 
 
 ## Contributing

docs/glossary.md

@@ -12,7 +12,7 @@ doctype
 type name
     The name of a single (atomic) type.
     A type name can include a {term}`type prefix`.
-    An {term}`annotation expression` can contain multiple typen names.
+    An {term}`annotation expression` can contain multiple type names.
     For example, the annotation expression `collections.abc.Iterable[int or float]` consists of the three names `collections.abc.Iterable`, `int` and `float`.
 
 type prefix

docs/index.md

@@ -17,9 +17,10 @@ It does so by supporting widely used readable conventions such as `array of dtyp
 ---
 
 :::{toctree}
-:caption: User guides
+:caption: Guides
 :maxdepth: 1
 
+installation
 introduction
 :::
 

docs/installation.md

@@ -0,0 +1,23 @@
+# Installation
+
+Docstub is available as a [package on PyPI](https://pypi.org/project/docstub/) and can be installed from there with your favorite package manager.
+For example:
+
+```shell
+pip install docstub
+```
+
+For static analysis, docstub does not need to be installed in the same Python environment as your project!
+You can use an isolated environment for docstub.
+So things like `pipx run docstub` or `uv tool run docstub` will work, too.
+
+
+## Development version
+
+In case you want to check out an unreleased version you can install the latest version directly from the repository with:
+
+```shell
+pip install 'docstub @ git+https://github.com/scientific-python/docstub'
+```
+
+You can append `@COMMIT_SHA` to the repository URL above to intall a specific version other that the `main` branch.

docs/introduction.md

@@ -1,20 +1,7 @@
 # Introduction
 
-## Installation
-
-Docstub is available as a [package on PyPI](https://pypi.org/project/docstub/) and can be installed from there with your favorite package manager. E.g.:
-
-```shell
-pip install docstub
-```
-
-In case you want to check out an unreleased version you can install directly from the repository with:
-
-```shell
-pip install 'docstub @ git+https://github.com/scientific-python/docstub'
-```
-
-To pin to a specific commit you can append `@COMMIT_SHA` to the repository URL above.
+This introduction will teach you how to use docstub and cover critical concepts.
+It assumes familiarity with Python and some familiarity with [static Typing](https://typing.python.org) and [packaging](https://packaging.python.org/en/latest/).
 
 
 ## First example
@@ -97,7 +84,7 @@ There are several interesting things to note here:
 
 ## Referencing types & nicknames
 
-To translate a type from a docstring into a valid type annotation, docstub needs to know where names in that type are defined from where to import them.
+To translate a type from a docstring into a valid type annotation, docstub needs to know how to import these types.
 Out of the box, docstub will know about builtin types such as `int` or `bool` that don't need an import, and types in `typing`, `collections.abc` from Python's standard library.
 It will source these from the Python environment it is installed in.
 In addition to that, docstub will collect all types in the package directory you are running it on.

docs/typing_syntax.md

@@ -1,23 +1,27 @@
 # Typing syntax in docstrings
 
-Docstub defines its own [grammar](../src/docstub/doctype.lark) to parse and transform type information in docstrings (doctypes) into valid Python type expressions.
+Docstub defines its own [grammar](../src/docstub/doctype.lark) to parse and transform type information in docstrings into valid Python type expressions.
 This grammar fully supports [Python's conventional typing syntax](https://typing.python.org/en/latest/index.html).
-So any type expression that is valid in Python, can be used in a docstrings as is.
+So any {term}`annotation expression` that is valid in Python, can be used in a docstrings as is.
 In addition, docstub extends this syntax with several "natural language" expressions that are commonly used in the scientific Python ecosystem.
 
-Docstrings should follow a form that is inspired by the NumPyDoc style:
+Docstrings should follow a form that is inspired by the [NumPyDoc style](https://numpydoc.readthedocs.io/en/latest/format.html):
 ```none
-Section name
+Section namew
 ------------
 name : doctype, optional_info
   Description.
 ```
 
 - `name` might be the name of a parameter, attribute or similar.
-- `doctype` contains the actual type information that will be transformed into a Python type (see also {term}`doctype`).
+- `doctype` contains the actual type information that will be transformed into an {term}`annotation expression`.
+  Here you can use the "natural language" expressions that are documented below.
 - `optional_info` is optional and captures anything after the first (top-level) comma.
   It is useful to provide additional information for readers.
-  Its presence and content doesn't currently affect the generated {term}`annotation expression`.
+  Its presence and content doesn't affect the generated {term}`annotation expression`.
+
+Combining multiple names that share a doctype and description is supported.
+  For example `a, b : int` is equivalent to defining both separately.
 
 
 ## Unions
@@ -116,12 +120,13 @@ See [issue 47](https://github.com/scientific-python/docstub/issues/47) for more
 
 ## reStructuredText role
 
-Since docstrings are also used to generate documentation with Sphinx, you may want to use [restructuredText roles](https://docutils.sourceforge.io/docs/ref/rst/roles.html) in your type annotations.
-Docstub allows for this anywhere where a qualified name can be used.
+Since docstrings are also used to generate documentation with Sphinx, you may want to use [restructuredText roles](https://docutils.sourceforge.io/docs/ref/rst/roles.html).
+This is supported anywhere in where a {term}`type name` is used in a {term}`doctype`.
 
-| Docstring type       | Python type annotation |
-|----------------------|------------------------|
-| `` `X` ``            | `X`                    |
-| ``:ref:`X` ``        | `X`                    |
-| ``:class:`Y.X` ``    | `Y.X`                  |
-| ``:py:class:`Y.X` `` | `Y.X`                  |
+| Docstring type          | Python type annotation |
+|-------------------------|------------------------|
+| `` `X` ``               | `X`                    |
+| ``:ref:`X` ``           | `X`                    |
+| ``:class:`X`[Y, ...] `` | `X[Y, ...]`            |
+| ``:class:`Y.X` ``       | `Y.X`                  |
+| ``:py:class:`Y.X` ``    | `Y.X`                  |