minor #1562 [docs] document new config values

Author: jrushlow

.doctor-rst.yaml

@@ -0,0 +1,80 @@
+rules:
+  american_english: ~
+  avoid_repetetive_words: ~
+  blank_line_after_anchor: ~
+  blank_line_after_directive: ~
+  blank_line_before_directive: ~
+  composer_dev_option_not_at_the_end: ~
+  correct_code_block_directive_based_on_the_content: ~
+  deprecated_directive_should_have_version: ~
+  ensure_bash_prompt_before_composer_command: ~
+  ensure_correct_format_for_phpfunction: ~
+  ensure_exactly_one_space_before_directive_type: ~
+  ensure_exactly_one_space_between_link_definition_and_link: ~
+  ensure_explicit_nullable_types: ~
+  ensure_github_directive_start_with_prefix:
+    prefix: 'Symfony'
+  ensure_link_bottom: ~
+  ensure_link_definition_contains_valid_url: ~
+  ensure_order_of_code_blocks_in_configuration_block: ~
+  ensure_php_reference_syntax: ~
+  extend_abstract_controller: ~
+  # extension_xlf_instead_of_xliff: ~
+  forbidden_directives:
+    directives:
+      - '.. index::'
+  indention: ~
+  lowercase_as_in_use_statements: ~
+  max_blank_lines:
+    max: 2
+  max_colons: ~
+  no_app_console: ~
+  no_attribute_redundant_parenthesis: ~
+  no_blank_line_after_filepath_in_php_code_block: ~
+  no_blank_line_after_filepath_in_twig_code_block: ~
+  no_blank_line_after_filepath_in_xml_code_block: ~
+  no_blank_line_after_filepath_in_yaml_code_block: ~
+  no_brackets_in_method_directive: ~
+  no_composer_req: ~
+  no_directive_after_shorthand: ~
+  no_duplicate_use_statements: ~
+  no_footnotes: ~
+  no_inheritdoc: ~
+  no_merge_conflict: ~
+  no_namespace_after_use_statements: ~
+  no_php_open_tag_in_code_block_php_directive: ~
+  no_space_before_self_xml_closing_tag: ~
+  only_backslashes_in_namespace_in_php_code_block: ~
+  only_backslashes_in_use_statements_in_php_code_block: ~
+  ordered_use_statements: ~
+  php_prefix_before_bin_console: ~
+  remove_trailing_whitespace: ~
+  replace_code_block_types: ~
+  replacement: ~
+  short_array_syntax: ~
+  space_between_label_and_link_in_doc: ~
+  space_between_label_and_link_in_ref: ~
+  string_replacement: ~
+  title_underline_length_must_match_title_length: ~
+  typo: ~
+  unused_links: ~
+  use_deprecated_directive_instead_of_versionadded: ~
+  use_named_constructor_without_new_keyword_rule: ~
+  use_https_xsd_urls: ~
+  valid_inline_highlighted_namespaces: ~
+  valid_use_statements: ~
+  versionadded_directive_should_have_version: ~
+  yaml_instead_of_yml_suffix: ~
+
+  #   master
+  versionadded_directive_major_version:
+    major_version: 1
+
+  versionadded_directive_min_version:
+    min_version: '1.0'
+
+  deprecated_directive_major_version:
+    major_version: 7
+
+  deprecated_directive_min_version:
+    min_version: '1.0'

.gitattributes

@@ -4,3 +4,4 @@
 /tests export-ignore
 /tools export-ignore
 docker-compose.yml export-ignore
+/_docs_build export-ignore

.github/workflows/ci-docs.yaml

@@ -0,0 +1,41 @@
+name: "CI Docs Analysis"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - 'main'
+  schedule:
+    -   cron: '0 0 * * *'
+
+env:
+  PHPUNIT_FLAGS: "-v"
+  SYMFONY_PHPUNIT_DIR: "$HOME/symfony-bridge/.phpunit"
+
+jobs:
+  doctor-rst:
+    name: Lint (DOCtor-RST)
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v3
+
+      - name: "Create cache dir"
+        run: mkdir .cache
+
+      - name: "Extract base branch name"
+        run: echo "branch=$(echo ${GITHUB_BASE_REF:=${GITHUB_REF##*/}})" >> $GITHUB_OUTPUT
+        id: extract_base_branch
+
+      - name: "Cache DOCtor-RST"
+        uses: actions/cache@v3
+        with:
+          path: .cache
+          key: ${{ runner.os }}-doctor-rst-${{ steps.extract_base_branch.outputs.branch }}
+
+      - name: "Run DOCtor-RST"
+        uses: docker://oskarstark/doctor-rst:1.61.1
+        with:
+          args: --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache

.gitignore

@@ -7,3 +7,5 @@
 /tools/*/composer.lock
 /tools/*/vendor
 /vendor/
+/_docs_build/vendor
+/_docs_build/output

README.md

@@ -25,3 +25,27 @@ B) The generated code itself may change between minor releases. This
 
 [1]: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html
 [2]: https://symfony.com/doc/current/contributing/code/bc.html
+
+---
+
+Build Documentation Locally
+---------------------------
+
+This is not needed for contributing, but it's useful if you would like to debug some
+issue in the docs or if you want to read MakerBundles Documentation offline.
+
+```bash
+$ cd _docs_build/
+
+$ composer install
+
+$ php build.php
+```
+
+After generating docs, serve them with the internal PHP server:
+
+```bash
+$ php -S localhost:8000 -t output/
+```
+
+Browse `http://localhost:8000` to read the docs.

_docs_build/build.php

@@ -0,0 +1,65 @@
+#!/usr/bin/env php
+<?php
+
+/*
+ * This file is part of the Symfony MakerBundle package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+require __DIR__.'/vendor/autoload.php';
+
+use Symfony\Component\Console\Application;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Style\SymfonyStyle;
+use SymfonyDocsBuilder\BuildConfig;
+use SymfonyDocsBuilder\DocBuilder;
+
+(new Application('Symfony Docs Builder', '1.0'))
+    ->register('build-docs')
+    ->addOption('generate-fjson-files', null, InputOption::VALUE_NONE, 'Use this option to generate docs both in HTML and JSON formats')
+    ->setCode(function (InputInterface $input, OutputInterface $output) {
+        $io = new SymfonyStyle($input, $output);
+        $io->text('Building all Symfony Docs...');
+
+        $outputDir = __DIR__.'/output';
+        $buildConfig = (new BuildConfig())
+            ->setSymfonyVersion('7.1')
+            ->setContentDir(__DIR__.'/../src/Resources/doc')
+            ->setOutputDir($outputDir)
+            ->setImagesDir(__DIR__.'/output/_images')
+            ->setImagesPublicPrefix('_images')
+            ->setTheme('rtd')
+            ->diableBuildCache()
+        ;
+
+        $buildConfig->setExcludedPaths(['.github/', '_build/']);
+
+        if (!$generateJsonFiles = $input->getOption('generate-fjson-files')) {
+            $buildConfig->disableJsonFileGeneration();
+        }
+
+        $io->comment(sprintf('cache: disabled / output file type(s): %s', $generateJsonFiles ? 'HTML and JSON' : 'HTML'));
+
+        $result = (new DocBuilder())->build($buildConfig);
+
+        if ($result->isSuccessful()) {
+            $io->success(sprintf('The Symfony Docs were successfully built at %s', realpath($outputDir)));
+
+            return 0;
+        }
+
+        $io->error(sprintf("There were some errors while building the docs:\n\n%s\n", $result->getErrorTrace()));
+        $io->newLine();
+        $io->comment('Tip: you can add the -v, -vv or -vvv flags to this command to get debug information.');
+
+        return 1;
+    })
+    ->getApplication()
+    ->setDefaultCommand('build-docs', true)
+    ->run();

_docs_build/composer.json

@@ -0,0 +1,22 @@
+{
+    "minimum-stability": "dev",
+    "prefer-stable": true,
+    "config": {
+        "platform": {
+            "php": "8.1.0"
+        },
+        "preferred-install": {
+            "*": "dist"
+        },
+        "sort-packages": true,
+        "allow-plugins": {
+            "symfony/flex": true
+        }
+    },
+    "require": {
+        "php": ">=8.1",
+        "symfony-tools/docs-builder": "^0.23",
+        "symfony/console": "^6.2",
+        "symfony/process": "^6.2"
+    }
+}