Refactoring docs into tutorials, howtos, explanation, and reference

adamcharnock · Jul 24, 2018 · 8d75348 · 8d75348
1 parent 09024db
commit 8d75348
Show file tree

Hide file tree

Showing 22 changed files with 88 additions and 46 deletions.
diff --git a/docs/concepts.md → docs/explanation/concepts.md b/docs/concepts.md → docs/explanation/concepts.md
@@ -134,7 +134,7 @@ This is useful when:
    with their implementation
 2. You wish the authoritative service to perform a known task in the background
 
-The [quickstart](quick-start.md#events) provides an example of the latter case.
+The [quickstart](/tutorial/quick-start.md#events) provides an example of the latter case.
 
 **Events provide at-least-once semantics.**
 
@@ -152,4 +152,4 @@ Lightbus ships with a Redis-backed implementation of each of these transports.
 
 Lightbus can be configured to use custom transports either globally, or on a per-API level.
 
-[simple-processes]: static/images/simple-processes.png
+[simple-processes]: /static/images/simple-processes.png
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
@@ -0,0 +1,8 @@
+# Explanation overview
+
+This section discusses the **theoretical and conceptual aspects
+of Lightbus**. This is in contrast to the more practical
+[tutorial] and [howto] sections.
+
+[tutorial]: /tutorial/index.md
+[howto]: /howto/index.md
diff --git a/docs/howto/event-sourcing.md b/docs/howto/event-sourcing.md
diff --git a/docs/howto/index.md b/docs/howto/index.md
@@ -0,0 +1,7 @@
+# Howto overview
+
+In this section we address **specific problems and common use cases**.
+As with the [tutorials] we will link to concepts as we go, but the
+priority here is to provide a clear path to a solution.
+
+[tutorials]: /tutorial/index.md
diff --git a/docs/howto/metrics.md b/docs/howto/metrics.md
diff --git a/docs/index.md b/docs/index.md
@@ -61,8 +61,8 @@ bus.auth.user_registered.listen(
 )
 ```
 
-To get started checkout the [installation](installation.md),
-[concepts](concepts.md),
-and [quickstart](quick-start.md) guides.
+To get started checkout the [installation](tutorial/installation.md),
+[concepts](explanation/concepts.md),
+and [quickstart](tutorial/quick-start.md) guides.
 
 [issue-1]: https://github.com/adamcharnock/lightbus/issues/1
diff --git a/docs/apis.md → docs/reference/apis.md b/docs/apis.md → docs/reference/apis.md
@@ -1,10 +1,10 @@
 
 !!! note
     We recommend read the [concepts](concepts.md) section before continuing
-    as this will give you a useful overview before delving into the details 
+    as this will give you a useful overview before delving into the details
     below.
 
-APIs specify the functionality available on the bus. To do this you 
+APIs specify the functionality available on the bus. To do this you
 define API classes within (or import API classes into) your `bus.py` file.
 
 For example:
@@ -17,17 +17,17 @@ class SupportCaseApi(Api):
     class Meta:
         # API name on the bus
         name = 'support.case'
-    
+
     # A procedure
     def get(self, id):
         return get_case_from_db(pk=id)
 ```
 
-A service can define zero or more APIs, and each API can contain 
+A service can define zero or more APIs, and each API can contain
 zero or more events and zero or more procedures.
 
-The `Meta` specifies options regarding the API, with `name` being 
-the only required option. The name specifies how the API will be 
+The `Meta` specifies options regarding the API, with `name` being
+the only required option. The name specifies how the API will be
 accessed on the bus.
 
 You could use the above API as follows:
@@ -51,21 +51,21 @@ bus.support.case.case_created.fire(
 
 ### `name (str)`
 
-Specifies the name of the API. This will determine how the API is addressed 
+Specifies the name of the API. This will determine how the API is addressed
 on the bus. See [naming](#naming), below.
 
 `name` is a required option.
 
 ### `auto_register (bool) = True`
 
-Should this API be registered with Lightbus upon import? This defaults to `True`, 
-but if you specifically wish to prevent the API from being automatically 
+Should this API be registered with Lightbus upon import? This defaults to `True`,
+but if you specifically wish to prevent the API from being automatically
 registered with Lightbus you should set this to `False`.
 
 ## Naming
 
-As you can see above, API names can contain periods to allow you 
-to structure your bus in a suitable form for your situation. 
+As you can see above, API names can contain periods to allow you
+to structure your bus in a suitable form for your situation.
 Some example API naming schemes may look like:
 
 ```coffeescript
@@ -86,7 +86,7 @@ Example: marketing.website.stats.get()
 
 ## Authoritative and non-authoritative
 
-The service which defines an API is *authoritative* for that API, and as 
+The service which defines an API is *authoritative* for that API, and as
 such can perform some actions that are not allowed by services accessing the API.
 
 A service which is authoritative for an API:
@@ -96,13 +96,13 @@ A service which is authoritative for an API:
    (i.e. by running a `lightbus run` process)
 3. May fire events for the API
 
-Conversely, a non-authoritative service may *not* perform the above actions. 
+Conversely, a non-authoritative service may *not* perform the above actions.
 For example, the online store service could not fire the `bus.support.case.case_created`
 event, nor should it import the `SupportCaseApi` class.
 
 ## Organising many APIs
 
-* Will lightbus recognise a bus package as well as a bus module? 
-  (i.e.`bus/__init__.py`?)
+* Will lightbus recognise a bus package as well as a bus module?
+  (i.e.`bus/__init__.py`?) TODO
 
 
diff --git a/docs/command-line-use.md → docs/reference/command-line-use.md b/docs/command-line-use.md → docs/reference/command-line-use.md
diff --git a/docs/configuration.md → docs/reference/configuration.md b/docs/configuration.md → docs/reference/configuration.md
diff --git a/docs/debugging.md → docs/reference/debugging.md b/docs/debugging.md → docs/reference/debugging.md
diff --git a/docs/events.md → docs/reference/events.md b/docs/events.md → docs/reference/events.md
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -0,0 +1,10 @@
+# Reference overview
+
+This section provides **detailed information regarding the specific
+features of Lightbus**.
+
+A grasp of the [tutorial] and [explantion] sections will
+be useful here.
+
+[tutorial]: /tutorial/index.md
+[explantion]: /explantion/index.md
diff --git a/docs/plugins.md → docs/reference/plugins.md b/docs/plugins.md → docs/reference/plugins.md
diff --git a/docs/rpcs.md → docs/reference/rpcs.md b/docs/rpcs.md → docs/reference/rpcs.md
diff --git a/docs/schema.md → docs/reference/schema.md b/docs/schema.md → docs/reference/schema.md
diff --git a/docs/transports.md → docs/reference/transports.md b/docs/transports.md → docs/reference/transports.md
diff --git a/docs/typing.md → docs/reference/typing.md b/docs/typing.md → docs/reference/typing.md
diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md
@@ -0,0 +1,5 @@
+# Tutorial overview
+
+Use this section to get **a practical concrete introduction to
+Lightbus**. We will link to concepts as we go, but the aim here
+is to get you up and running quickly.
diff --git a/docs/installation.md → docs/tutorial/installation.md b/docs/installation.md → docs/tutorial/installation.md
diff --git a/docs/quick-start.md → docs/tutorial/quick-start.md b/docs/quick-start.md → docs/tutorial/quick-start.md
@@ -1,17 +1,17 @@
 !!! note
-    We recommend read the [concepts](concepts.md) section before continuing
+    We recommend read the [concepts](/explanation/concepts.md) section before continuing
     as this will give you a useful overview before delving into the details
     below.
 
 ## Requirements
 
 Before continuing, ensure you have completed the following steps detailed in
-the [installation section](installation.md):
+the [installation section](/tutorial/installation.md):
 
 * Installed Python 3.6 or above
 * Installed Lightbus
 * Running a Redis server (built from the Redis unstable branch)
-* Read the [concepts section](concepts.md)
+* Read the [concepts section](/explanation/concepts.md)
 
 ## Anatomy lesson
 
@@ -112,7 +112,7 @@ which contains the class definition within its codebase. Lightbus only
 allows the authoritative service to fire events for an API. Any service can
 listen for any event.
 
-We will talk more about this in [concepts](concepts.md). For now let's look
+We will talk more about this in [concepts](/explanation/concepts.md). For now let's look
 at some code. Below we modify our `AuthApi` in `bus.py` to add a `user_registered`
 event. We also use the `before_server_start()` hook to setup a listener for
 that event:
@@ -182,4 +182,4 @@ good starting point. Reading through the remainder of this documentation should
 a wider awareness of the features available and underlying concepts.
 
 
-[lightbus-run]: static/images/quickstart-lightbus-run.png
+[lightbus-run]: /static/images/quickstart-lightbus-run.png
diff --git a/docs/worked-example.md → docs/tutorial/worked-example.md b/docs/worked-example.md → docs/tutorial/worked-example.md
@@ -21,8 +21,8 @@ A passing familiarity with [Flask] may be useful, but is not required. [Honcho]
 will assist us in running the various processes required for our services.
 
 We will assume you
-have already read and completed the [installation](installation.md),
-[quick start](quick-start.md), and [concepts](concepts.md) sections.
+have already read and completed the [installation](/tutorial/installation.md),
+[quick start](/tutorial/quick-start.md), and [concepts](/explanation/concepts.md) sections.
 
 ## Image resizing service
 
@@ -416,9 +416,9 @@ $ honcho start -f Procfile_combined
 [Flask]: http://flask.pocoo.org/
 [ex03_worked_example]: https://github.com/adamcharnock/lightbus/tree/master/lightbus_examples/ex03_worked_example
 [Procfile]: https://github.com/adamcharnock/lightbus/blob/mater/lightbus_examples/ex03_worked_example/Procfile
-[web-log]: static/images/worked-example-flask-log.png
-[honcho-startup]: static/images/worked-example-honcho-startup.png
-[honcho-page-view]: static/images/worked-example-honcho-page-view.png
+[web-log]: /static/images/worked-example-flask-log.png
+[honcho-startup]: /static/images/worked-example-honcho-startup.png
+[honcho-page-view]: /static/images/worked-example-honcho-page-view.png
 [127.0.0.1:5001]: http://127.0.0.1:5001
 [127.0.0.1:5000]: http://127.0.0.1:5000
 [aiohttp]: https://aiohttp.readthedocs.io/
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -28,24 +28,36 @@ theme:
   favicon: ""
   logo:
     icon: "\uE915"
+  feature:
+    tabs: true
 
 pages:
-  - Introduction: index.md
-  - Installation: installation.md
-  - Concepts: concepts.md
-  - Quick start: quick-start.md
-  - Worked example: worked-example.md
-  - Typing: typing.md
-  - APIs: apis.md
-  - Remote prcedure calls: rpcs.md
-  - Events: events.md
-  - Configuration: configuration.md
-  - Schema: schema.md
-  - Transports: transports.md
-  - Command line use: command-line-use.md
-  - Debugging: debugging.md
-  - Plugins: plugins.md
-  - Contributing: contributing.md
+  - Home: index.md
+  - Tutorials:
+    - Overview: tutorial/index.md
+    - Installation: tutorial/installation.md
+    - Quick start: tutorial/quick-start.md
+    - Worked example: tutorial/worked-example.md
+  - Howto*:
+    - Overview: howto/index.md
+    - Use Lightbus for realtime metrics: howto/metrics.md
+    - Use Lightbus for event sourcing: howto/event-sourcing.md
+  - Explanation:
+    - Overview: explanation/index.md
+    - Concepts: explanation/concepts.md
+    - Contributing*: contributing.md
+  - Reference:
+    - Overview: reference/index.md
+    - Typing*: reference/typing.md
+    - APIs: reference/apis.md
+    - Remote prcedure calls: reference/rpcs.md
+    - Events: reference/events.md
+    - Configuration: reference/configuration.md
+    - Schema: reference/schema.md
+    - Transports*: reference/transports.md
+    - Command line use*: reference/command-line-use.md
+    - Debugging*: reference/debugging.md
+    - Plugins*: reference/plugins.md
 
 # Extensions
 markdown_extensions: