Merge pull request #577 from humanmade/701-documentation-linting-issues

Reformat and correct docs files after linting

Author: mikelittle

docs/README.md

@@ -1,7 +1,8 @@
 # Documentation
 
-![](./assets/banner-docs.png)
+![Documentation banner](./assets/banner-docs.png)
 
 The Documentation module provides documentation for Altis.
 
-This module is used to generate the documentation you're currently reading, and can also be used [for your own custom project documentation](custom-documentation.md).
+This module is used to generate the documentation you're currently reading, and can also be
+used [for your own custom project documentation](custom-documentation.md).

docs/additional-doc-set.md

@@ -15,49 +15,49 @@ const PROJECT_DOCS_SET_ID = 'project-docs';
 
 // Custom user documentation Set.
 add_filter( 'altis.documentation.sets', static function ( array $sets ) {
-	if ( empty( $sets[ PROJECT_DOCS_SET_ID ] ) ) {
-		// Create our documentation set
-		$doc_set = new Set( PROJECT_DOCS_SET_ID, 'Project Documentation' );
+    if ( empty( $sets[ PROJECT_DOCS_SET_ID ] ) ) {
+        // Create our documentation set
+        $doc_set = new Set( PROJECT_DOCS_SET_ID, 'Project Documentation' );
 
-		// Add all documentation pages in a group.
-		$proj_docs = dirname( __DIR__ ) . '/project-docs';
-		$group = new Group( 'Project Guides' );
-		Altis\Documentation\add_docs_for_group( $group, $proj_docs );
+        // Add all documentation pages in a group.
+        $proj_docs = dirname( __DIR__ ) . '/project-docs';
+        $group = new Group( 'Project Guides' );
+        Altis\Documentation\add_docs_for_group( $group, $proj_docs );
 
-		// Add the group to the set
-		$doc_set->add_group( 'guides-group', $group );
-		$doc_set->set_default_group_id( 'guides-group' );
+        // Add the group to the set
+        $doc_set->add_group( 'guides-group', $group );
+        $doc_set->set_default_group_id( 'guides-group' );
 
-		// Add our set to the others.
-		$sets[ PROJECT_DOCS_SET_ID ] = $doc_set;
-	}
+        // Add our set to the others.
+        $sets[ PROJECT_DOCS_SET_ID ] = $doc_set;
+    }
 
-	return $sets;
+    return $sets;
 } );
 
 ```
 
 If you wish to include a link to your additional documentation page under a different menu, for example a top level
-functional menu you can. Add a submenu page under a different menu but with the same menu id as the system uses.
+functional menu you can. Add a sub-menu page under a different menu but with the same menu id as the system uses.
 
 ```php
 const PROJECT_DOCS_SET_ID = 'project-docs';
 
 add_action( 'admin_menu', static function () {
-	$doc_set = \Altis\Documentation\get_documentation_set( PROJECT_DOCS_SET_ID );
-	$page_hook = add_submenu_page(
-		'my-custom-menu-id',
-		$doc_set->get_title(),
-		$doc_set->get_title(),
-		'edit_posts',
-		sprintf( '%s-%s', \Altis\Documentation\UI\PAGE_SLUG, PROJECT_DOCS_SET_ID ),
-		static function () {
-			\Altis\Documentation\UI\render_page( PROJECT_DOCS_SET_ID );
-		} );
-
-	// Add custom call back to load styles and scripts.
-	add_action( "load-$page_hook", static function () {
-		\Altis\Documentation\UI\load_page_assets();
-	} );
+    $doc_set = \Altis\Documentation\get_documentation_set( PROJECT_DOCS_SET_ID );
+    $page_hook = add_submenu_page(
+        'my-custom-menu-id',
+        $doc_set->get_title(),
+        $doc_set->get_title(),
+        'edit_posts',
+        sprintf( '%s-%s', \Altis\Documentation\UI\PAGE_SLUG, PROJECT_DOCS_SET_ID ),
+        static function () {
+            \Altis\Documentation\UI\render_page( PROJECT_DOCS_SET_ID );
+        } );
+
+    // Add custom call back to load styles and scripts.
+    add_action( "load-$page_hook", static function () {
+        \Altis\Documentation\UI\load_page_assets();
+    } );
 } );
 ```

docs/custom-documentation.md

@@ -1,21 +1,28 @@
 # Custom Documentation
 
-The documentation module can be used for your own [custom modules](docs://getting-started/custom-modules.md), allowing you to build an internal knowledge base for your development team.
+The documentation module can be used for your own [custom modules](docs://getting-started/custom-modules.md), allowing you to build
+an internal knowledge base for your development team.
 
-The built-in Documentation Set is intended for developer documentation. To add your documentation to the Developer Docs set, see the information below. To add additional sets of Documentation, perhaps for the users of your system, see [Additional Documentation Sets](./additional-doc-set.md).     
+The built-in Documentation Set is intended for developer documentation. To add your documentation to the Developer Docs set, see the
+information below. To add additional sets of Documentation, perhaps for the users of your system,
+see [Additional Documentation Sets](./additional-doc-set.md).
 
 ## Documentation Structure
 
-Each module provides its own documentation. The Documentation module also includes project-level documentation, such as the [Guides](docs://guides/) and [Getting Started](docs://getting-started/) documentation.
-
-The Documentation module automatically takes Markdown files from a `docs/` directory within each module's root directory, and parses them into pages. These are hierarchically-structured based on the directory structure, with `README.md` acting as the index file for each directory.
+Each module provides its own documentation. The Documentation module also includes project-level documentation, such as
+the [Guides](docs://guides/) and [Getting Started](docs://getting-started/) documentation.
 
+The Documentation module automatically takes Markdown files from a `docs/` directory within each module's root directory, and parses
+them into pages. These are hierarchically-structured based on the directory structure, with `README.md` acting as the index file for
+each directory.
 
 ## Formatting
 
-Documentation files are standard Markdown, as supported by [Parsedown](https://parsedown.org/). They also support [relative and in-project links](linking.md).
+Documentation files are standard Markdown, as supported by [Parsedown](https://parsedown.org/). They also
+support [relative and in-project links](linking.md).
 
-Markdown files can contain YAML front-matter, which specifies a list of "meta" information about the page itself. The following fields are supported:
+Markdown files can contain YAML front-matter, which specifies a list of "meta" information about the page itself. The following
+fields are supported:
 
 ```yaml
 ---
@@ -30,18 +37,21 @@ order: 0
 ---
 ```
 
-Headers have automatically generated fragment IDs attached for in-page linking. This automatic ID can be overridden if desired by suffixing with `{#id-name}`:
+Headers have automatically generated fragment IDs attached for in-page linking. This automatic ID can be overridden if desired by
+suffixing with `{#id-name}`:
 
 ```md
 # Header Name {#override-id}
 ```
 
-
 ## Custom Behavior
 
-Internally, the Documentation module stores an ordered list of "groups", which have an ID and associated top-level pages. Each page has metadata, content, and potentially sub-pages.
+Internally, the Documentation module stores an ordered list of "groups", which have an ID and associated top-level pages. Each page
+has metadata, content, and potentially sub-pages.
 
-The `altis.documentation.groups` filter is provided the ordered list of `Group` objects, and you can add or remove groups from here, or manipulate existing groups. The `Documentation\add_docs_for_group()` function may be useful for this; see `Documentation\filter_add_dev_docs_set()` to see how Altis generates developer documentation for modules.
+The `altis.documentation.groups` filter is provided the ordered list of `Group` objects, and you can add or remove groups from here,
+or manipulate existing groups. The `Documentation\add_docs_for_group()` function may be useful for this;
+see `Documentation\filter_add_dev_docs_set()` to see how Altis generates developer documentation for modules.
 
 For example, to add your own Guides-style section:
 
@@ -50,10 +60,10 @@ use Altis\Documentation\Group;
 use function Altis\Documentation\add_docs_for_group;
 
 add_filter( 'altis.documentation.groups', function ( array $groups, string $set_id ) {
-	if ( $set_id === 'dev-docs' ) {
-		$groups['project-guides'] = new Group( 'Project Guides' );
-		add_docs_for_group( $groups['project-guides'], __DIR__ . '/our-guides' );
-	}
-	return $groups;
+    if ( $set_id === 'dev-docs' ) {
+        $groups['project-guides'] = new Group( 'Project Guides' );
+        add_docs_for_group( $groups['project-guides'], __DIR__ . '/our-guides' );
+    }
+    return $groups;
 } );
 ```

docs/linking.md

@@ -1,14 +1,15 @@
 ---
 order: 10
 ---
+
 # Linking
 
 The Documentation module supports relative links and cross-linking between pages in documentation.
 
-
 ## Relative Links
 
-Within a given module's documentation, you can use relative links between files. These will be resolved during the rendering of the documentation.
+Within a given module's documentation, you can use relative links between files. These will be resolved during the rendering of the
+documentation.
 
 For example, to link to a document in the same directory called `doc.md`, you can format your link as:
 
@@ -24,17 +25,20 @@ To link to a document in a subdirectory or a parent directory, use similar relat
 [Document in a subdirectory](./subdir/doc.md)
 ```
 
-Note that relative links can only be used between documents in a single module, and links to other modules should instead use cross-linking.
-
+Note that relative links can only be used between documents in a single module, and links to other modules should instead use
+cross-linking.
 
 ## Cross-Linking
 
 Cross-linking refers to links from one module to another. This allows creating richer documentation, tying together various modules.
 
-To link from one module to another, use the special URL scheme `docs://`. This should be followed by the name of the documentation group (typically the module ID), followed by a slash, followed by the page ID (typically a file path within the module's documentation directory). You can also link between Sets of documentation, for example from a developer document to a custom project guide, using an optional leading Set ID. 
+To link from one module to another, use the special URL scheme `docs://`. This should be followed by the name of the documentation
+group (typically the module ID), followed by a slash, followed by the page ID (typically a file path within the module's
+documentation directory). You can also link between Sets of documentation, for example from a developer document to a custom project
+guide, using an optional leading Set ID.
 The full format is:
 
-```
+```md
 docs://[{set}/]{group}/{id}
 ```
 
@@ -47,30 +51,32 @@ Consult the [branding documentation](docs://cms/branding.md)
 Or to link to a `block-templates.md` document in the 'Layout guide' of your project's custom documentation set.
 
 ```md
-All available [block templates](docs://project-docs/layout/block-templates.md) are listed in the [Layout guide](docs://project-docs/layout/)
+All available [block templates](docs://project-docs/layout/block-templates.md) are listed in
+the [Layout guide](docs://project-docs/layout/)
 ```
 
-**Note:** while documentation group IDs generally align with module IDs, some special groups exist for meta documentation. This includes the Getting Started (ID `getting-started`) and Guides (ID `guides`) documentation, which are located in the `other-docs` directory of the Documentation module.
-
+**Note:** while documentation group IDs generally align with module IDs, some special groups exist for meta documentation. This
+includes the Getting Started (ID `getting-started`) and Guides (ID `guides`) documentation, which are located in the `other-docs`
+directory of the Documentation module.
 
 ## Internal Linking
 
 To enable rich documentation, you can link to internal resources on the site.
 
-These links use the special `internal://` URL scheme. This is followed by the type of internal link, followed by a slash, followed by an optional additional path. The following types are available:
+These links use the special `internal://` URL scheme. This is followed by the type of internal link, followed by a slash, followed
+by an optional additional path. The following types are available:
 
-* `internal://home/{path}` - URL on the frontend, equivalent to `home_url( $path )`
-* `internal://site/{path}` - URL on the backend, equivalent to `site_url( $path )`
-* `internal://admin/{path}` - Page in the admin, equivalent to `admin_url( $path )`
-* `internal://network-admin/{path}` - Page in the network admin, equivalent to `network_admin_url( $path )`
+- `internal://home/{path}` - URL on the frontend, equivalent to `home_url( $path )`
+- `internal://site/{path}` - URL on the backend, equivalent to `site_url( $path )`
+- `internal://admin/{path}` - Page in the admin, equivalent to `admin_url( $path )`
+- `internal://network-admin/{path}` - Page in the network admin, equivalent to `network_admin_url( $path )`
 
 For example, to link to the current user's profile page:
 
 ```md
 [View your profile](internal://admin/profile.php)
 ```
 
-
 ## Link to support
 
 You can easily display a direct link to the Altis support ticket system, pre-filled with the current environment stack name.