Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: title iteration #39

Merged
merged 3 commits into from
Feb 21, 2025
Merged

Docs: title iteration #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
65ff156
Docs: update titles for API and global functions
kraftbj Feb 21, 2025
7abc5d8
Docs: improve capitalization of rest api
kraftbj Feb 21, 2025
064c6fb
Docs: sort via hierarchy
kraftbj Feb 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions docs/bin/generate-manifest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 );
Expand Down
86 changes: 77 additions & 9 deletions docs/bin/generate-parsed-md.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ class DocGenerator {
/**
* PHP Parser instance.
*
* @var ParserFactory
* @var \PhpParser\Parser
*/
private $parser;

Expand Down Expand Up @@ -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, '/' );
Expand Down Expand Up @@ -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";
}

Expand All @@ -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.
*/
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
Loading