Docs: title iteration (#39)

Author: kraftbj

docs/bin/generate-manifest.php

@@ -118,6 +118,42 @@
 	}
 }
 
+/**
+ * Sort entries hierarchically - null parents first, then by depth.
+ *
+ * @param array $manifest The manifest to sort.
+ * @return array Sorted manifest.
+ */
+function sort_manifest_hierarchically( $manifest ) {
+	// First, group by depth
+	$grouped = array();
+	foreach ( $manifest as $key => $entry ) {
+		$depth = substr_count( $key, '/' );
+		if ( ! isset( $grouped[ $depth ] ) ) {
+			$grouped[ $depth ] = array();
+		}
+		$grouped[ $depth ][ $key ] = $entry;
+	}
+
+	// Sort depths
+	ksort( $grouped );
+
+	// Merge back maintaining order
+	$sorted = array();
+	foreach ( $grouped as $depth => $entries ) {
+		// Sort entries within each depth
+		ksort( $entries );
+		foreach ( $entries as $key => $entry ) {
+			$sorted[ $key ] = $entry;
+		}
+	}
+
+	return $sorted;
+}
+
+// Before writing the manifest, sort it hierarchically
+$manifest = sort_manifest_hierarchically( $manifest );
+
 file_put_contents( $root . '/bin/manifest.json', json_encode( (object) $manifest, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES ) );
 
 $count = count( $manifest );

docs/bin/generate-parsed-md.php

@@ -23,7 +23,7 @@ class DocGenerator {
 	/**
 	 * PHP Parser instance.
 	 *
-	 * @var ParserFactory
+	 * @var \PhpParser\Parser
 	 */
 	private $parser;
 
@@ -96,7 +96,8 @@ class DocGenerator {
 	 * @param string $output_dir Directory where documentation will be generated.
 	 */
 	public function __construct( $output_dir ) {
-		$this->parser    = ( new ParserFactory() )->create( ParserFactory::PREFER_PHP7 );
+		$parser_factory  = new ParserFactory();
+		$this->parser    = $parser_factory->create( ParserFactory::PREFER_PHP7 );
 		$this->traverser = new NodeTraverser();
 		$this->traverser->addVisitor( new NameResolver() );
 		$this->output_dir = rtrim( $output_dir, '/' );
@@ -415,13 +416,16 @@ private function generate_index_files() {
 			if ( '' === $dir ) {
 				$index_content = '# Code Reference' . "\n\n";
 			} else {
-				$index_content = '#' . ( '.' === $dir ? ' Code Reference' : ' ' . ucwords( str_replace( '/', ' ', $dir ) ) ) . "\n\n";
+				// Format directory name for title
+				$dir_title     = $this->format_directory_title( $dir );
+				$index_content = '# ' . $dir_title . "\n\n";
 			}
+
 			$index_content .= '## Files' . "\n\n";
 
 			foreach ( $files as $file ) {
 				$basename       = basename( $file, '.md' );
-				$title          = ucwords( str_replace( '-', ' ', $basename ) );
+				$title          = $this->format_file_title( $basename );
 				$index_content .= '- [' . $title . '](' . $basename . ')' . "\n";
 			}
 
@@ -438,6 +442,49 @@ private function generate_index_files() {
 		}
 	}
 
+	/**
+	 * Format directory title with special cases.
+	 *
+	 * @param string $dir Directory name.
+	 * @return string Formatted title.
+	 */
+	private function format_directory_title( $dir ) {
+		if ( 'rest-api' === $dir ) {
+			return 'REST API';
+		}
+		return '.' === $dir ? 'Code Reference' : ucwords( str_replace( '/', ' ', $dir ) );
+	}
+
+	/**
+	 * Format file title with special cases.
+	 *
+	 * @param string $basename File basename.
+	 * @return string Formatted title.
+	 */
+	private function format_file_title( $basename ) {
+		// Replace common patterns
+		$title = str_replace(
+			array(
+				'rest-api',
+				'acf-rest-api',
+				'class-acf-rest',
+				'-file',
+			),
+			array(
+				'REST API',
+				'ACF REST API',
+				'Class ACF REST',
+				'',
+			),
+			$basename
+		);
+
+		// Convert to title case and handle special words
+		$title = ucwords( str_replace( '-', ' ', $title ) );
+
+		return $title;
+	}
+
 	/**
 	 * Generate the META.md file containing undocumented elements and duplicate hooks.
 	 */
@@ -611,7 +658,7 @@ private function save_markdown( $file, $docs ) {
 				mkdir( $output_dir, 0755, true );
 			}
 
-			$markdown = $this->generate_markdown( $docs );
+			$markdown = $this->generate_markdown( $docs, $relative_path );
 			file_put_contents( $output_path, $markdown );
 
 			// Track files by directory for index generation
@@ -626,24 +673,33 @@ private function save_markdown( $file, $docs ) {
 	/**
 	 * Generate markdown content from documentation array.
 	 *
-	 * @param array $docs Documentation organized by type.
+	 * @param array  $docs         Documentation organized by type.
+	 * @param string $source_path  The relative path to the source file.
 	 * @return string Generated markdown content.
 	 */
-	private function generate_markdown( $docs ) {
+	private function generate_markdown( $docs, $source_path ) {
 		$markdown = '';
 
 		// Generate standalone functions documentation
 		if ( ! empty( $docs['functions'] ) ) {
-			$markdown .= '# Global Functions' . "\n\n";
+			// Convert file path to title
+			// e.g., "api/api-helpers.php" becomes "API Helpers"
+			$file_title = basename( $source_path, self::PHP_EXT );
+			$file_title = str_replace( '-', ' ', $file_title );
+			$file_title = ucwords( $file_title );
+			// Special handling for "api" to become "API"
+			$file_title = preg_replace( '/\b[Aa]pi\b/', 'API', $file_title );
+			$markdown  .= $this->format_title( $file_title . ' Global Functions' ) . "\n\n";
 			foreach ( $docs['functions'] as $name => $doc ) {
 				$markdown .= '## `' . $name . '()`' . "\n\n";
 				$markdown .= trim( $doc ) . "\n\n\n";  // Add extra newline after each function
 			}
 			$markdown .= "---\n\n";
 		}
 
+		// Handle class documentation (unchanged)
 		if ( isset( $docs['class'] ) ) {
-			$markdown .= '# ' . $docs['class']['name'] . "\n\n";
+			$markdown .= $this->format_title( $docs['class']['name'] ) . "\n\n";
 			$markdown .= trim( $docs['class']['doc'] ) . "\n\n";
 
 			// Add properties section
@@ -668,6 +724,18 @@ private function generate_markdown( $docs ) {
 		$markdown = rtrim( rtrim( $markdown ), "\n" ) . "\n";
 		return $markdown;
 	}
+
+	/**
+	 * Format a title for markdown documentation.
+	 *
+	 * @param string $title The title to format.
+	 * @return string Formatted title.
+	 */
+	private function format_title( $title ) {
+		// Convert "Api" or "api" to "API"
+		$title = preg_replace( '/\b[Aa]pi\b/', 'API', $title );
+		return '# ' . $title;
+	}
 }
 
 // Parse command line arguments