Finish documentation

Author: oprypin

README.md

@@ -1,16 +1,11 @@
 # mkdocstrings-crystal
 
-[Crystal][] language doc generator for [MkDocs][], via [mkdocstrings][].
+**[Crystal][] language doc generator for [MkDocs][], via [mkdocstrings][].**
 
 [![PyPI](https://img.shields.io/pypi/v/mkdocstrings-crystal)](https://pypi.org/project/mkdocstrings-crystal/)
 [![GitHub](https://img.shields.io/github/license/oprypin/mkdocstrings-crystal)](LICENSE.md)
 [![GitHub Workflow Status](https://img.shields.io/github/workflow/status/oprypin/mkdocstrings-crystal/CI)](https://github.com/oprypin/mkdocstrings-crystal/actions?query=event%3Apush+branch%3Amaster)
 
-[crystal]: https://crystal-lang.org/
-[mkdocs]: https://www.mkdocs.org/
-[mkdocstrings]: https://pawamoy.github.io/mkdocstrings/
-[virtualenv]: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
-
 ## Introduction
 
 *mkdocstrings-crystal* allows you to insert API documentation (generated from [Crystal][]'s source code and doc comments) as part of any page on a [MkDocs][] site.
@@ -21,6 +16,8 @@ To install it, run (possibly in a [virtualenv][]):
 pip install mkdocstrings-crystal
 ```
 
+**Continue to the [documentation site][].**
+
 ## Usage
 
 With [MkDocs][], add/merge this base config as your _mkdocs.yml_:
@@ -59,3 +56,12 @@ This, of course, happens as part of a normal MkDocs build process:
 mkdocs build  # generate from docs/ into site/
 mkdocs serve  # live preview
 ```
+
+**Continue to the [documentation site][].**
+
+
+[crystal]: https://crystal-lang.org/
+[mkdocs]: https://www.mkdocs.org/
+[mkdocstrings]: https://pawamoy.github.io/mkdocstrings/
+[virtualenv]: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
+[documentation site]: https://oprypin.github.io/mkdocstrings-crystal/

docs/README.md

@@ -8,11 +8,11 @@ Crystal language doc generator for [MkDocs][], via [mkdocstrings][].
 $ pip install mkdocstrings-crystal
 ```
 
-[Continue with **quickstart**](quickstart/README.md).
+[Continue with **quickstart**](quickstart/index.md).
 
 ## Introduction
 
-Crystal has [its own easy-to-use generator of API documentation sites](https://crystal-lang.org/reference/using_the_compiler/#crystal-docs), but it's very rigid, as it doesn't attempt to do anything other than API documentation, so [these sites](https://crystal-lang.org/api/) end up being very isolated and prevent the author from presenting some kind of *story* about using their library.
+Crystal has [its own easy-to-use generator of API documentation sites](https://crystal-lang.org/reference/using_the_compiler/#crystal-docs), but it's very rigid, as it doesn't attempt to do anything other than API documentation, so [these sites](https://crystal-lang.org/api/0.35.1/Process.html) end up being very isolated and prevent the author from presenting some kind of *story* about using their library.
 
 Instead, this plugin is all about that *story*. It's very inspiring to look at [Python's documentation for `subprocess`](https://docs.python.org/3/library/subprocess.html), and hard to imagine a world in which this document is just an alphabetic dump of the functions in it.
 
@@ -51,7 +51,9 @@ Then, in any `docs/**/*.md` file, you can **mention a Crystal identifier alone o
 
 -- and in the output this will be replaced with generated API documentation for it, much like Crystal's own doc generator does.
 
-This, of course, happens as part of a normal MkDocs build process:
+Learn more about this syntax: [in *mkdocstrings* in general](https://pawamoy.github.io/mkdocstrings/usage/) (Crystal specifics are below).
+
+The auto-replacement, of course, happens as part of a normal MkDocs build process:
 
 ```console
 $ mkdocs build  # generate from docs/ into site/
@@ -66,7 +68,7 @@ But another powerful feature of this plugin is that you can **[cross-reference](
 
 ## Usage details
 
-We have been talking about seamlessly inserting Crystal documentation, but where is it coming from? The implementation actually still uses `crystal doc` generator but through [its JSON output](https://github.com/crystal-lang/crystal/pull/4746). So the requirement is the same: the source code that the doc comments and signatures are coming from is assumed to be somewhere under the _src/_ directory. If that isn't appropriate, you can select the wanted entry files by passing them to `crystal doc`, as part of [`crystal_docs_flags`](configuration.md#crystal_docs_flags) ([example](https://github.com/oprypin/athena-website/blob/c06906d5933421120c76e15fd6f529eeb5c48221/mkdocs.yml#L33)).
+We have been talking about seamlessly inserting Crystal documentation, but where is it coming from? The implementation actually still uses `crystal doc` generator but through [its JSON output](https://github.com/crystal-lang/crystal/pull/4746). So the requirement is the same: the source code that the doc comments and signatures are coming from is assumed to be somewhere under the _src/_ directory. If that isn't appropriate, you can select the wanted entry files by passing them to `crystal doc`, as part of [`crystal_docs_flags`](configuration.md#crystal_docs_flags) (see "Custom source directories" [in Showcase](showcase.md#athena-framework)).
 
 Continue to [Configuration](configuration.md).
 

docs/configuration.md

@@ -2,7 +2,7 @@
 
 ## Handler options
 
-(See also: [mkdocstrings global options](https://pawamoy.github.io/mkdocstrings/usage/#global-options))
+(See also: [*mkdocstrings* global options](https://pawamoy.github.io/mkdocstrings/usage/#global-options))
 
 ### `crystal_docs_flags:`
 
@@ -16,7 +16,7 @@ A list of command line arguments to pass to `crystal doc`. Mainly used to choose
 :    Set to `true` to also recursively render all `Foo::Sub::Types` whenever rendering a given class `Foo`.
 
 `file_filters:` [list of strings]
-:    If a particular module spans over several files, you might want to choose to render only the sub-items (see `nested_types`) that came from a particular file. These patterns ared regular expressions (not anchored) applied to the file path. Negating the patterns is done by starting it with `!` (which is then excluded from the following regex).
+:    If a particular module spans over several files, you might want to choose to render only the sub-items (see `nested_types`) that came from a particular file. These patterns are regular expressions (not anchored) applied to the file path. Negating the patterns is done by starting it with `!` (which is then excluded from the following regex). This is very similar to [what's done in *mkdocstrings*](https://pawamoy.github.io/mkdocstrings/reference/handlers/python/#mkdocstrings.handlers.python.PythonCollector.default_config)
 
 ### `rendering:`
 

docs/extras.md

@@ -45,7 +45,7 @@ These are the built-in mogrifier implementations:
 
 [Browse the API exposed by the root `DocType`](api.md).
 
-## Support for [MkDocs "gen-files" plugin](https://github.com/oprypin/mkdocs-gen-files)
+## Support for [MkDocs "gen-files" plugin](https://oprypin.github.io/mkdocs-gen-files)
 
 There's no special support, these just work well together.
 

docs/quickstart/README.md

@@ -1,15 +1,19 @@
-You can publish the website
+# Continuous build and publishing
 
-```yaml  linenums="1" hl_lines="2 13 17 19 23"
---8<-- "examples/modern/.github/workflow/deploy-docs.yml"
-```
+You can build and publish the website automatically on push using GitHub Pages and GitHub Actions. Here's our recommendation:
 
-???+ question "Why configure like this"
-    Crystal Nightly is needed because this plugin relies on some improvements to Crystal's doc generator that haven't made it into a release yet.
+???+ example ".github/workflows/deploy-docs.yml"
+    ```yaml  linenums="1" hl_lines="2 13 17 19 23"
+    --8<-- "examples/simple/.github/workflows/deploy-docs.yml"
+    ```
 
+???+ question "Why configure like this"
+    * Do *not* disable the workflow for non-*master* branches or pull requests. It is nice to ensure that the site builds (there can be errors!), instead at the bottom we prevent only the actual *deploy* action from being executed on non-*master*/non-*pushes*.
+    * Crystal Nightly is needed because this plugin relies on some improvements to Crystal's doc generator that haven't made it into a release yet.
+    * Dependencies are installed from `requirements.txt`. Make sure you've [populated it](python-dependencies.md).
 
 !!! tip
     You can freely have a "dev" branch for working on docs that aren't ready for release yet. Then just merge it into the main one when ready.
 
 !!! tip
-    Your docs don't have to be in the same repository as the main code. In fact, the doc site can span several projects! See [Athena's website](https://github.com/oprypin/athena-website) as an example (of particular interest are `mkdocs.yml` (`crystal_docs_flags:`) and `shard*` files.
+    Your docs don't have to be in the same repository as the main code. In fact, the doc site can span several projects! See "Multi-repo setup" [in Showcase](../showcase.md#athena-framework).

docs/quickstart/ci.md

@@ -0,0 +1,98 @@
+# Quick-start guide
+
+This assumes you already have some project in Crystal, say, a file `src/foo.cr`.
+
+??? example "src/foo.cr"
+    ```crystal
+    --8<-- "examples/simple/src/foo.cr"
+    ```
+
+Hosting on GitHub is also assumed, though that's easy to adapt.
+
+We'll be working from the project's root directory (the one that *contains* `src`).
+
+[View the final file layout](https://github.com/oprypin/mkdocstrings-crystal/tree/master/examples/simple/)
+
+## Dependencies
+
+The dependencies that we'll be using can be installed like this:
+
+```console
+$ pip install mkdocs-material mkdocstrings-crystal
+```
+
+This assumes you have [Python][] installed, with `pip` available.
+
+!!! tip
+    You might want to install these in a [virtualenv][] (i.e. localized just to this project).
+
+    And check out how to **[manage Python dependencies](python-dependencies.md)** long-term.
+
+## Base config
+
+Let's configure [MkDocs][] with *mkdocstrings-crystal*. Add/merge this config as your `mkdocs.yml`:
+
+???+ example "mkdocs.yml"
+    ```yaml
+    --8<-- "examples/simple/mkdocs.yml"
+    ```
+
+???+ question "Why configure like this"
+    `theme:` `material`
+    :   [material](https://squidfunk.github.io/mkdocs-material/) is the only supported [MkDocs theme](https://www.mkdocs.org/user-guide/styling-your-docs/#third-party-themes).
+
+    `repo_url` and `icon`
+    :   Link back to your repository nicely. [See more](https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/).
+
+    `extra_css`
+    :   Don't forget to copy and include the [recommended styles](../styling.md#recommended-styles).
+
+    `mkdocstrings:` `default_handler: crystal`
+    :   Activate the upstream *mkdocstrings* plugin and tell it to collect items from Crystal, not Python, by default.
+
+    `watch: [src]`
+    :   Watch a directory for [auto-reload](https://pawamoy.github.io/mkdocstrings/usage/#watch-directories). Assuming the sources are under `src/`.
+
+    [`pymdownx.*` extensions](https://facelessuser.github.io/pymdown-extensions/)
+    :   Python-Markdown is an "old-school" Markdown parser, and these extensions bring the defaults more in line with what people are used to now.
+
+    `deduplicate-toc` extension
+    :   This is actually an integral part of *mkdocstrings-crystal*. [Read more](../extras.md#deduplicate-toc-extension).
+
+## Add an API doc page
+
+???+ example "docs/api.md"
+    ```md
+    --8<-- "examples/simple/docs/api.md"
+    ```
+
+## Add a normal page
+
+???+ example "docs/index.md"
+    ```md
+    --8<-- "examples/simple/docs/index.md"
+    ```
+
+We linked directly to an identifier here, and *mkdocstrings* knows which page it's on and automatically links that. See: [identifier linking syntax](../README.md#identifier-linking-syntax).
+
+## View the site
+
+That's it -- we're ready!
+
+```shell
+mkdocs build  # generate from docs/ into site/
+mkdocs serve  # live preview
+```
+
+## Next steps
+
+If you find that you have too many classes and you don't want to manually create files with callouts to them, there are ways to automate it, and good examples are in [the migration-oriented guide](migrate.md#base-config).
+
+Otherwise, you're encouraged to curate per-topic pages with your API items. See "Manually curated docs page" [in Showcase](../showcase.md#crystal-chipmunk) for examples.
+
+And you'll probably want to [set up a navigation config](https://www.mkdocs.org/user-guide/configuration/#documentation-layout) anyway.
+
+
+[mkdocs]: https://www.mkdocs.org/
+[python]: https://www.python.org/
+[virtualenv]: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment