Skip to content

Commit 8686e12

Browse files
jrushlowjrushlow
committed
build docs in dev
1 parent 05d9b21 commit 8686e12

8 files changed

+2914
-0
lines changed

‎.gitattributes

+1
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@
44
/tests export-ignore
55
/tools export-ignore
66
docker-compose.yml export-ignore
7+
/_docs_build export-ignore

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,5 @@
77
/tools/*/composer.lock
88
/tools/*/vendor
99
/vendor/
10+
/_docs_build/vendor
11+
/_docs_build/output

‎README.md

+24
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,27 @@ B) The generated code itself may change between minor releases. This
2525

2626
[1]: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html
2727
[2]: https://symfony.com/doc/current/contributing/code/bc.html
28+
29+
---
30+
31+
Build Documentation Locally
32+
---------------------------
33+
34+
This is not needed for contributing, but it's useful if you would like to debug some
35+
issue in the docs or if you want to read MakerBundles Documentation offline.
36+
37+
```bash
38+
$ cd _docs_build/
39+
40+
$ composer install
41+
42+
$ php build.php
43+
```
44+
45+
After generating docs, serve them with the internal PHP server:
46+
47+
```bash
48+
$ php -S localhost:8000 -t output/
49+
```
50+
51+
Browse `http://localhost:8000` to read the docs.

‎_docs_build/build.php

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
#!/usr/bin/env php
2+
<?php
3+
require __DIR__.'/vendor/autoload.php';
4+
5+
use Symfony\Component\Console\Application;
6+
use Symfony\Component\Console\Input\InputInterface;
7+
use Symfony\Component\Console\Output\OutputInterface;
8+
use Symfony\Component\Console\Input\InputOption;
9+
use Symfony\Component\Console\Style\SymfonyStyle;
10+
use SymfonyDocsBuilder\BuildConfig;
11+
use SymfonyDocsBuilder\DocBuilder;
12+
13+
(new Application('Symfony Docs Builder', '1.0'))
14+
->register('build-docs')
15+
->addOption('generate-fjson-files', null, InputOption::VALUE_NONE, 'Use this option to generate docs both in HTML and JSON formats')
16+
->addOption('disable-cache', null, InputOption::VALUE_NONE, 'Use this option to force a full regeneration of all doc contents')
17+
->setCode(function(InputInterface $input, OutputInterface $output) {
18+
$io = new SymfonyStyle($input, $output);
19+
$io->text('Building all Symfony Docs...');
20+
21+
$outputDir = __DIR__.'/output';
22+
$buildConfig = (new BuildConfig())
23+
->setSymfonyVersion('7.1')
24+
->setContentDir(__DIR__.'/../src/Resources/doc')
25+
->setOutputDir($outputDir)
26+
->setImagesDir(__DIR__.'/output/_images')
27+
->setImagesPublicPrefix('_images')
28+
->setTheme('rtd')
29+
;
30+
31+
$buildConfig->setExcludedPaths(['.github/', '_build/']);
32+
33+
if (!$generateJsonFiles = $input->getOption('generate-fjson-files')) {
34+
$buildConfig->disableJsonFileGeneration();
35+
}
36+
37+
if ($isCacheDisabled = $input->getOption('disable-cache')) {
38+
$buildConfig->disableBuildCache();
39+
}
40+
41+
$io->comment(sprintf('cache: %s / output file type(s): %s', $isCacheDisabled ? 'disabled' : 'enabled', $generateJsonFiles ? 'HTML and JSON' : 'HTML'));
42+
if (!$isCacheDisabled) {
43+
$io->comment('Tip: add the --disable-cache option to this command to force the re-build of all docs.');
44+
}
45+
46+
$result = (new DocBuilder())->build($buildConfig);
47+
48+
if ($result->isSuccessful()) {
49+
// fix assets URLs to make them absolute (otherwise, they don't work in subdirectories)
50+
$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($outputDir));
51+
52+
foreach (new RegexIterator($iterator, '/^.+\.html$/i', RegexIterator::GET_MATCH) as $match) {
53+
$htmlFilePath = array_shift($match);
54+
$htmlContents = file_get_contents($htmlFilePath);
55+
56+
$htmlRelativeFilePath = str_replace($outputDir.'/', '', $htmlFilePath);
57+
$subdirLevel = substr_count($htmlRelativeFilePath, '/');
58+
$baseHref = str_repeat('../', $subdirLevel);
59+
60+
$htmlContents = str_replace('<head>', '<head><base href="'.$baseHref.'">', $htmlContents);
61+
$htmlContents = str_replace('<img src="/_images/', '<img src="_images/', $htmlContents);
62+
file_put_contents($htmlFilePath, $htmlContents);
63+
}
64+
65+
foreach (new RegexIterator($iterator, '/^.+\.css/i', RegexIterator::GET_MATCH) as $match) {
66+
$htmlFilePath = array_shift($match);
67+
$htmlContents = file_get_contents($htmlFilePath);
68+
file_put_contents($htmlFilePath, str_replace('fonts/', '../fonts/', $htmlContents));
69+
}
70+
71+
$io->success(sprintf("The Symfony Docs were successfully built at %s", realpath($outputDir)));
72+
} else {
73+
$io->error(sprintf("There were some errors while building the docs:\n\n%s\n", $result->getErrorTrace()));
74+
$io->newLine();
75+
$io->comment('Tip: you can add the -v, -vv or -vvv flags to this command to get debug information.');
76+
77+
return 1;
78+
}
79+
80+
return 0;
81+
})
82+
->getApplication()
83+
->setDefaultCommand('build-docs', true)
84+
->run();

‎_docs_build/composer.json

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"minimum-stability": "dev",
3+
"prefer-stable": true,
4+
"config": {
5+
"platform": {
6+
"php": "8.1.0"
7+
},
8+
"preferred-install": {
9+
"*": "dist"
10+
},
11+
"sort-packages": true,
12+
"allow-plugins": {
13+
"symfony/flex": true
14+
}
15+
},
16+
"require": {
17+
"php": ">=8.1",
18+
"symfony-tools/docs-builder": "^0.23",
19+
"symfony/console": "^6.2",
20+
"symfony/process": "^6.2"
21+
}
22+
}

0 commit comments

Comments
 (0)