docs: using.md cleanup (#255)

* Update settings manager link
* Fix formatting in plugin section and add link
* Simplify "I want to build a platform" section
Add links to relevant sections so it's clear where the user should go next.
* Use code literals for code things
* Clarify that the settings manager code samples are two different examples

docs/usability/using_settings_manager.md

@@ -6,21 +6,22 @@ provides needed information such as scope, repositories, command-line options,
 and other things. This allows scopes to be dynamic but in a standardized way.
 Below is a sample implementation of a settings manager for your reference.
 
-This is an implementation of both Update and Setup Settings Managers using
+This is an implementation of both `UpdateSettingsManager` and `SetupSettingsManager` using
 multiple inheritance. You can see that they add their own command line argument
 `--production` that is used to toggle the use of the `production` scope. For any
 given invocable, you can pass `-h` or `--help` to show a list of available
 command line options. If you call `-c <path> --help` this list will also include
 command line options provided from the settings file you provided.
 
-These examples are for building a platform; which needs an instance of
-UpdateSettingsManager, SetupSettingsManager, BuildSettingsManager, and
-UefiBuilder.
+These examples are for building a platform, which needs instances of
+`UpdateSettingsManager`, `SetupSettingsManager`, `BuildSettingsManager`, and
+`UefiBuilder`. The instances can be grouped together in a single class, or separated into different classes.
 
-## All settings are grouped together
+## Examples
 
-```python
+### All settings grouped together
 
+```python
 class SettingsManager(UpdateSettingsManager, SetupSettingsManager, BuildSettingsManager):
     def __init__(self):
         SCRIPT_PATH = os.path.dirname(os.path.abspath(__file__))
@@ -93,7 +94,7 @@ class PlatformBuilder(UefiBuilder):
         raise Exception("Flashing not supported")
 ```
 
-## Build Settings is grouped with UefiBuilder, other settings are separate
+### Build Settings grouped with `UefiBuilder`, other settings separate
 
 ```python
 class SettingsManager(UpdateSettingsManager, SetupSettingsManager):
@@ -177,9 +178,9 @@ class PlatformBuilder(UefiBuilder, BuildSettingsManager):
 
 ## A note on multi-inheritance
 
-You might notice if you implement several classes, how does the system know
-which AddCommandLineOptions to call when it's doing update vs setup? The answer
+If you implement several classes, you might wonder how the system knows
+which `AddCommandLineOptions` to call when it's doing update vs setup? The answer
 is that it doesn't. It's a classic case of the diamond problem and python's
-answer for this is the MRO. Currently, our advice is to not call super into the
-settings classes in this package. You can call super to your classes that you
+answer for this is the MRO. Currently, our advice is to not call `super` into the
+settings classes in this package. You can call `super` to your classes that you
 have implemented that subclass pytool settings classes.

docs/using.md

@@ -20,17 +20,15 @@ these utilities.
 ### 1) I want to build a platform
 
 You have an EDK2 implementation, a platform DSC, and a platform FDF? Great! You
-are one settings file away from a great platform building experience.
+are one [settings file](usability/using_settings_manager.md) away from a great platform building experience.
 
-If you use submodules, you will find stuart_setup helpful for submodule sync and
-update.
+Once your settings file is created and configured, you can use the [stuart commands](#what-can-ask-stuart-to-do) start building:
 
-stuart_update walks through the environment and downloads all the tools that the
+1. `stuart_setup` - Syncs and updates submodules that your project uses.
+2. `stuart_update` - Walks through the environment and downloads all the tools that the
 environment says it needs.
-
-To build the platform and assemble a ROM according to your FDF, invoke
-stuart_build. Your UefiBuilder instance will provide the opportunity to tweak or
-override at every step of the process.
+3. `stuart_build` - Builds the platform and assembles a ROM according to your FDF. Your `UefiBuilder` instance (in the
+   settings file) will provide the opportunity to tweak or override at every step of the process.
 
 ### 2) I want to manage a codebase
 
@@ -40,9 +38,9 @@ the images in your file tree and make sure they are encoded correctly.
 
 These use cases will fit into our 'CI' tools category.
 
-stuart_ci_setup can be called to clone whatever code repositories would be
+`stuart_ci_setup` can be called to clone whatever code repositories would be
 required for this operation. stuart_update can be called to download all the
-tools the environment says it needs. From there, stuart_ci_build takes a list of
+tools the environment says it needs. From there, `stuart_ci_build` takes a list of
 packages to look at and runs all plugins on each package.
 
 ### 3) I want to do something new
@@ -52,9 +50,9 @@ the process specifically to your use case? You need something to do on the
 weekend?
 
 Great! We have built out invocables to be as robust and extensible as possible.
-We have base_abstract_invocable, which asks for the bare minimum required for
+We have `base_abstract_invocable`, which asks for the bare minimum required for
 environment initialization in the form of abstract functions that you can fill
-out. We have also built edk2_invocable, on top of base_abstract_invocable, which
+out. We have also built `edk2_invocable`, on top of `base_abstract_invocable`, which
 handles getting setup and providing settings in a manner we hope will work well
 for most everyone.
 
@@ -87,14 +85,17 @@ everything has been downloaded and is present in the tree.
 ### plugin
 
 Plugins are code files that can be executed according to their scope. There are
-four different interfaces you could choose to implement:
+three different interfaces you could choose to implement:
 
-1) UefiBuildPlugin - Used for platform builds, this interface has two hooks:
-   pre-build and post-build. 2) CiBuildPlugin - Our CI process is to run all
+1. `UefiBuildPlugin` - Used for platform builds, this interface has two hooks: pre-build and post-build.
+2. `CiBuildPlugin` - Our CI process is to run all
    CiBuildPlugins for each package. Each plugin is essentially a test that will
-   be executed on the given code tree. 3) UefiHelperPlugin - Registers one or
+   be executed on the given code tree.
+3. `UefiHelperPlugin` - Registers one or
    more functions that can called by any part of the build system.
 
+[Plugin manager documentation](usability/using_plugin_manager.md)
+
 ### CI
 
 Continuous integration: Constantly interrogating your code base to make sure it
@@ -134,7 +135,7 @@ be passed in. This way, the invocable script gets all the information it needs
 without needing to carry the overhead of command line parsing and loading the
 class.
 
-[settings manager documentation](features/feature_settings_manager.md)
+[settings manager documentation](usability/using_settings_manager.md)
 
 ### stuart
 
@@ -150,17 +151,17 @@ be helpful for a wide variety workflows.
 
 ### stuart_setup
 
-Sets up git repo based on the gitsubmodule file in your repo. It checks to make
+Sets up the git repo based on the gitsubmodule file in your repo. It checks to make
 sure the required repos as provided by settings manager are present.
 
 ### stuart_update
 
-Reads ext_dep files in environment and downloads the appropriate files for the
+Reads ext_dep files in the environment and downloads the appropriate files for the
 active scopes currently defined. These scopes come from the settings manager.
 
 ### stuart_build
 
-Builds a platform. Requires an instance of UefiBuilder to be provided in
+Builds a platform. Requires an instance of `UefiBuilder` to be provided in
 addition to the settings manager.
 
 ### stuart_ci_setup
@@ -179,8 +180,8 @@ checkpoint between each test.
 
 ### .gitignore
 
-We have a couple .gitignore items that are important for keeping git from
-getting it's hands on Stuart!
+We have a couple `.gitignore` items that are important for keeping git from
+getting its hands on Stuart!
 
 ```.gitignore
 *.pyc