Generate the documentation list

danielbachhuber · danielbachhuber · commit 2efe80849a84 · 2016-03-04T08:43:40.000-08:00
diff --git a/Phakefile.php b/Phakefile.php
@@ -209,6 +209,51 @@ function gen_cmd_pages( $cmd, $parent = array() ) {
 	file_put_contents( '_includes/internal-api-list.html', $out );
 });
 
+desc( 'Update the /docs/ page.' );
+task( 'doc-list', function( $app ){
+	$docs = array(
+		'Guides'       => array(),
+		'References'   => array(),
+		'Contributing' => array(),
+		'Misc'         => array(),
+	);
+	foreach( glob( __DIR__ . '/docs/*/index.md' ) as $file ) {
+		$contents = file_get_contents( $file );
+		$parts = explode( '---', $contents );
+		$header = $parts[1];
+		preg_match( '#category:\s(.+)#', $header, $matches );
+		if ( ! empty( $matches[1] ) && array_key_exists( $matches[1], $docs ) ) {
+			$category = $matches[1];
+		} else {
+			$category = 'Misc';
+		}
+		preg_match( '#title:\s(.+)#', $header, $matches );
+		$title = ! empty( $matches[1] ) ? $matches[1] : '';
+		preg_match( '#description:\s(.+)#', $header, $matches );
+		$description = ! empty( $matches[1] ) ? $matches[1] : '';
+		$docs[ $category ][] = array(
+			'path'        => basename( dirname( $file ) ),
+			'title'       => $title,
+			'description' => $description,
+		);
+	}
+	$out = '';
+	foreach( $docs as $category => $cat_docs ) {
+		$out .= '<h3>' . $category . '</h3>' . PHP_EOL . PHP_EOL;
+		$out .= '<ul>' . PHP_EOL;
+		foreach( $cat_docs as $cat_doc ) {
+			$out .= '<li><a href="/docs/' . $cat_doc['path'] . '/"><strong>' . $cat_doc['title'] . '</strong></a>';
+			if ( ! empty( $cat_doc['description'] ) ) {
+				$out .= ' - ' . $cat_doc['description'];
+			}
+			$out .= '</li>' . PHP_EOL;
+		}
+		$out .= '</ul>' . PHP_EOL . PHP_EOL;
+	}
+
+	file_put_contents( '_includes/doc-list.html', $out );
+});
+
 desc( 'Build the site.' );
-task( 'default', 'cmd-list', 'param-list', 'internal-api-list' );
+task( 'default', 'cmd-list', 'param-list', 'internal-api-list', 'doc-list' );
 
diff --git a/_includes/doc-list.html b/_includes/doc-list.html
@@ -0,0 +1,22 @@
+<h3>Guides</h3>
+
+<ul>
+<li><a href="/docs/installing/"><strong>Installing</strong></a> - Recommended and alternative installation mechanisms.</li>
+</ul>
+
+<h3>References</h3>
+
+<ul>
+<li><a href="/docs/internal-api/"><strong>Internal API</strong></a> - Stable utilities considered safe to use in community commands.</li>
+</ul>
+
+<h3>Contributing</h3>
+
+<ul>
+</ul>
+
+<h3>Misc</h3>
+
+<ul>
+</ul>
+
diff --git a/_includes/header.html b/_includes/header.html
@@ -12,6 +12,7 @@
 		<link rel="alternate" type="application/atom+xml" href="/atom.xml" title="Atom Feed">
 
 		<title>{{ page.title }} | WP-CLI</title>
+		<meta name="description" content="{{ page.description }}">
 	</head>
 
 	{% if page.display_global_parameters %}
diff --git a/_layouts/doc.html b/_layouts/doc.html
@@ -0,0 +1,10 @@
+{% include header.html %}
+
+{% capture page_url %}{{ page.url | remove:'index.html' }}{% endcapture %}
+{% if page_url != '/docs/' %}
+<a href="/docs/">Docs</a> &raquo; {{ page.category }}
+{% endif %}
+
+{{ content }}
+
+{% include footer.html %}
diff --git a/_templates/internal-api.mustache b/_templates/internal-api.mustache
@@ -3,7 +3,7 @@ layout: default
 title: {{full_name}}()
 ---
 
-<a href="/docs/internal-api/">Internal API</a> &raquo; {{category}}
+<a href="/docs/">Docs</a> &raquo; <a href="/docs/internal-api/">Internal API</a> &raquo; {{category}}
 
 ## {{full_name}}()
 
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,13 @@
+---
+layout: doc
+title: Documentation
+description: Helpful guides and resources for using WP-CLI.
+---
+
+## Documentation
+
+Here are some helpful guides and resources for using WP-CLI.
+
+Can't find what you're looking for? [Open an issue](https://github.com/wp-cli/wp-cli/issues) to request improvements.
+
+{% include doc-list.html %}
diff --git a/docs/installing/index.md b/docs/installing/index.md
@@ -1,6 +1,8 @@
 ---
-layout: default
+layout: doc
 title: Installing
+category: Guides
+description: Recommended and alternative installation mechanisms.
 ---
 
 ## Recommended Installation
diff --git a/docs/internal-api/index.md b/docs/internal-api/index.md
@@ -1,6 +1,8 @@
 ---
-layout: default
+layout: doc
 title: Internal API
+category: References
+description: Stable utilities considered safe to use in community commands.
 ---
 
 ## Internal API
