symfony-tools / docs-builder Goto Github PK

See https://github.com/weaverryan/docs-builder/pull/69#issuecomment-800065133 for details.

Hello,

i think this PR https://github.com/weaverryan/docs-builder/pull/44/files introduced a small HTML problem: all ids are duplicated between <hX> element and related <div class="section">
meaning this rst:

Title
===

results in this invalid html code:

<div class="section" id="title">
    <h1 id="title">
        <a class="headerlink" href="#title" title="Permalink to this headline">Title</a>
    </h1>
</div>

we should either override section-begin.html.twig file or remove the id of the title.

I'm working on integrating the docs builder in a new symfony.com section. So far it works great (I'm using a new RstParser class instead of generating it via the command or the PHAR).

The only issue I have is with images. I need to change their URL pattern and I don't know how to do it:

// Wrongly generated URL
/bundles/<the-bundle-name>/<the-bundle-branch>/_images/<the-image-name>.png

// The URL we need
/doc/bundles/<the-bundle-name>/<the-bundle-branch>/_images/<the-image-name>.png

I have this:

$builder = new Builder(KernelFactory::createKernel($buildContext));
$builder->build($buildContext->getSourceDir(), $buildContext->getOutputDir());

If I add this before the ->build() call, it changes all links, not only images, so it breaks everything:

$builder->getConfiguration()->setBaseUrl('doc');

And if I use this, nothing happens, so I don't know how this callable works:

$builder->getConfiguration()->setBaseUrlEnabledCallable(fn($path) => dd($path));

Could you please help me? Thanks!

In this file: https://github.com/sonata-project/SonataAdminBundle/blob/3.x/docs/getting_started/the_form_view.rst

The old RST parser correctly creates the content sections (the <img> is outside of the "Using Tabs" section because it belongs to the previous section):

However, the new doc builder considers that the image is part of the "Using Tabs" section. This is wrong:

Blog posts are rendered directly from a raw rst string, once it's created.
Then we need to extract some logic from the command to another layer of service. This way, the build process could be called by a symfony.com controller, for instance

In #121 I had to disable a test because I cannot make it work. The datetime.html introduces issues very frequently whenever we update anything. We should probably refactor it.

This file: https://github.com/sonata-project/SonataAdminBundle/blob/3.x/docs/reference/dashboard.rst has things like these:

The ``Admin`` list block
------------------------

Configuring the ``Admin`` list
------------------------------

Using the ``Admin`` service declaration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These are wrongly processed in the TOC, which shows the links like this:

The contents of the heading are correctly displayed, but the "weird alphanumeric string" leaks to the permalink too:

At the end of this file -> https://raw.githubusercontent.com/sonata-project/SonataAdminBundle/3.x/docs/getting_started/installation.rst we have this content:

The Admin Interface
-------------------

You've finished the installation process, congratulations. If you fire up the
server, you can now visit the admin page on http://localhost:8000/admin

.. note::

    This tutorial assumes you are using the build-in server using the
    ``bin/console server:start`` (or ``server:run``) command.

.. figure:: ../images/getting_started_empty_dashboard.png
   :align: center
   :alt: Sonata Dashboard
   :width: 700px

As you can see, the admin panel is very empty. This is because no bundle has
provided admin functionality for the admin bundle yet. Fortunately, you'll
learn how to do this in the :doc:`next chapter <creating_an_admin>`.

.. _`installation chapter`: https://getcomposer.org/doc/00-intro.md
.. _SonataDoctrineORMAdminBundle: https://sonata-project.org/bundles/doctrine-orm-admin/master/doc/index.html
.. _SonataDoctrineMongoDBAdminBundle: https://sonata-project.org/bundles/mongo-admin/master/doc/index.html
.. _SonataDoctrinePhpcrAdminBundle: https://sonata-project.org/bundles/doctrine-phpcr-admin/master/doc/index.html

In the old RST parser, the last paragraph is correctly rendered as something apart from the previous figure:

However, in the new parser, the last paragraph is wrongly considered the "figcaption" of the figure:

Detected on https://symfony.com/doc/current/contributing/code_of_conduct/care_team.html which has the following content in the source:

Here are all the members of the CARE team (in alphabetic order). You can contact
any of them directly using the contact details below or you can also contact all
of them at once by emailing **[email protected]**:

The docs builder currently render this like that:

<p>Here are all the members of the CARE team (in alphabetic order). You can contact
any of them directly using the contact details below or you can also contact all
of them at once by emailing <a href="mailto:**[email protected]" class="reference internal">**[email protected]</a>**:</p>

the ** before the email is taken as part of the email reference, which breaks the mailto link (the link goes to the wrong email) and is probably also what breaks the bold rendering.

Related to this: symfony/symfony-docs#16302

In Sphinx we could do this:

Learn more
----------
.. toctree::
    :maxdepth: 1
    :glob:

    /console
    /components/console/*
    /components/console/helpers/index
    /console/*

Sphinx recognizes that you have added /components/console/helpers/index explicitly and then it doesn't include it repeatedly in /components/console/*

When using Docs Builder, we must do this change:

 Learn more
 ----------
 .. toctree::
     :maxdepth: 1
     :glob:

     /console
     /components/console/*
-    /components/console/helpers/index
     /console/*

This is not an essential feature, but it's nice when you want to include some specific article behind all the other articles.

The #152 fix works beautifully ... but there's something missing in it. The TOC links seems to be not updated.

Example:

• in the TOC: https://symfony.com/doc/current/components/string.html#slugger
• in the body: https://symfony.com/doc/current/components/string.html#slugger-1

Thanks

In the *.fjson files generated by Sphinx, there's a boolean option called display_toc. Sphinx explains it as follows:

display_toc
    A boolean that is True if the toc contains more than one entry.

Source: https://www.sphinx-doc.org/en/1.0/builders.html#serialization-builder-details

This is used in some parts of Symfony to decide if the TOC is displayed or not. So we should probably keep it for compatibility. Thanks!

see weaverryan/symfony-docs#17

This file https://github.com/liip/LiipImagineBundle/blob/2.x/Resources/doc/filters/general.rst uses :strong: to make text bold:

Background Options
~~~~~~~~~~~~~~~~~~

:strong:`color:` ``string``
    Sets the background color HEX value. The default color is white (``#fff``).

:strong:`size:` ``int[]``
    Sets the generated background size as an integer array containing the dimensions
    as width and height values.

Sphinx supports it:

But docs-builder doesn't:

Question: should we implement this?

My opinion: if it's not too complicated, yes. Otherwise, "won't fix".

Originally reported by @karaka200 and @almaz-free in symfony/symfony-docs#16449:

For build documentation locally, after executing php build.php command, the following error is displayed:

In FileIncluder.php line 47:

  Include ".. include:: /components/require_autoload.rst.inc" does not exist or is not readable.

same error on windows 10 with php-8.1.2-Win32-vs16-x64.zip
(on linux no error)
In file FileIncluder.php on line 44 variable $path conatin:
"C:\projects\symfony-docs-6.0/components/components/require_autoload.rst.inc"
but real path is
"C:\projects\symfony-docs-6.0\components\require_autoload.rst.inc"

It works on macOS too, so I guess this is only an issue on Windows. Let's see if someone can try to debug and fix this. Thanks!

Just ran across this while working on a different project - issue does not cover something specific to docs-builder but is more or less a reminder to dig into this a bit more as time allows.

aside links break from secondary pages

the env var SYMFONY_VERSION should be used to handle which version of the doc might be parsed

see weaverryan/symfony-docs#16

Sphinx describes the parents option as:

parents, prev and next:
    Information about related chapters in the TOC tree. Each relation is a
    dictionary with the keys link (HREF for the relation) and title (title
    of the related document, as HTML). parents is a list of relations,
    while prev and next are a single relation.

Source: https://www.sphinx-doc.org/en/1.0/builders.html#serialization-builder-details

An example in practice:

This RST file from the Symfony Docs ->
https://github.com/symfony/symfony-docs/blob/5.x/contributing/code/bugs.rst

Is included in this index.rst from the section it belongs to:
https://github.com/symfony/symfony-docs/blob/5.x/contributing/code/index.rst

Which in turn is included in this index.rst from the main section:
https://github.com/symfony/symfony-docs/blob/5.x/contributing/index.rst

When the *.fjson is generated, it contains the following parents:

"parents": [
    {"link": "../index.html", "title": "Contributing"},
    {"link": "index.html", "title": "Contributing Code"}
]

This is used in some parts of symfony.com to generate the breadcrumbs, so we'd need to re-add this option. I don't know if it's very complicated to do so or not 😐

Not sure if we're building the 5.3 docs up on production w/ docs builder yet - but if we are, I stumbled on:

https://symfony.com/doc/5.3/reference/twig_reference.html

The "Backed By Jolicode" feels like its missing something.

Sometimes we link to a file in a recipe. That's pretty easy - it's just a link to a file on GitHub. Except for one interesting complication. For example, on Symfony 4.1, if I want to link to a file in the FrameworkBundle recipe, I need to link to the 3.3 directory (e.g. https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/config/bootstrap.php). But on 4.2, suddenly there is a new recipe and so a new directory (e.g. https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/4.2/config/bootstrap.php).

This is a perfect example of something that we should not need to handle by hand, and in fact IF we handle it by hand, we will eventually mess it up (e.g. forget to update the URLs when there is a new recipe for Symfony 4.3).

In this article --> https://raw.githubusercontent.com/EasyCorp/EasyAdminBundle/master/doc/upgrade.rst we have this:

Removed Features
----------------

EasyAdmin 3 removes some features of the previous versions which are no longer
considered useful:

* The ``design.brand_color`` config option has been removed because you can't
  customize the backend design by changing just this value. If you still want to
  do that, use the following code in your dashboard class::

      class DashboardController extends AbstractDashboardController
      {
          // ...

          public function configureAssets(): Assets
          {
              return Assets::new()
                  // ...
                  ->addHtmlContentToHead('<style>:root { --color-primary: #123456; }</style>');
          }
      }

* The ``default: true`` option to set the default backend page has been removed.
  Use the :doc:`dashboard </dashboards>` index as the default page or redirect
  to the desired page inside the dashboard controller action.

In the current symfony.com it works OK:

But the new parser doesn't understand it:

We might consider this "won't fix because it's too edgy" and then rewrite the original RST content.

Hi Ryan 👋

I'd like to make some changes and add some features in this project. I know we're using this as a dependency in symfony/symfony-docs repository, so I'm proposing to pin the version used in Symfony Docs (see symfony/symfony-docs#15018) to a specific commit, which is the last merge you did in this repository (weaverryan@e388a6f).

Do you think it's safe to merge things after that change in Symfony Docs is merged? Or do you prefer to do things differently? Thanks!

We were checking the generated fjson files and we found that next option works perfectly, but the related prev option is always null.

Example:

This file -> https://github.com/EasyCorp/EasyAdminBundle/blob/master/doc/index.rst

The crud item is after dashboards and before design, but in the fjson file we get this:

    "next": {
        "title": "Design",
        "link": "design.html"
    },
    "prev": null,

Now, if you look at design, you should find crud as prev. Instead, you find this:

    "next": {
        "title": "Fields",
        "link": "fields.html"
    },
    "prev": null,

Given that next is working perfectly, maybe this has a non-complex fix? Thanks!

Here's the detailed log:

Error when building SonataAdminBundle docs
Warning: Undefined array key -1

  #0 vendor/doctrine/rst-parser/lib/Nodes/TableNode.php(188): Doctrine\RST\Nodes\TableNode->compileSim
  pleTable()
  #1 vendor/doctrine/rst-parser/lib/Nodes/TableNode.php(148): Doctrine\RST\Nodes\TableNode->compile()
  #2 vendor/doctrine/rst-parser/lib/Parser/DocumentParser.php(511): Doctrine\RST\Nodes\TableNode->fina
  lize(Object(Doctrine\RST\Parser))
  #3 vendor/doctrine/rst-parser/lib/Parser/DocumentParser.php(315): Doctrine\RST\Parser\DocumentParser
  ->flush()
  #4 vendor/doctrine/rst-parser/lib/Parser/DocumentParser.php(205): Doctrine\RST\Parser\DocumentParser
  ->parseLine('')
  #5 vendor/doctrine/rst-parser/lib/Parser/DocumentParser.php(145): Doctrine\RST\Parser\DocumentParser
  ->parseLines('\nField Types\n==...')
  #6 vendor/doctrine/rst-parser/lib/Parser.php(178): Doctrine\RST\Parser\DocumentParser->parse('Field
  Types\n===...')
  #7 vendor/doctrine/rst-parser/lib/Parser.php(162): Doctrine\RST\Parser->parseLocal('Field Types\n===
  ...')
  #8 vendor/doctrine/rst-parser/lib/Parser.php(200): Doctrine\RST\Parser->parse('Field Types\n===...')
  #9 vendor/doctrine/rst-parser/lib/Builder/ParseQueueProcessor.php(71): Doctrine\RST\Parser->parseFil
  e('/Users/javier/w...')
  #10 vendor/doctrine/rst-parser/lib/Builder/ParseQueueProcessor.php(59): Doctrine\RST\Builder\ParseQu
  eueProcessor->processFile('reference/field...')
  #11 vendor/doctrine/rst-parser/lib/Builder.php(220): Doctrine\RST\Builder\ParseQueueProcessor->proce
  ss(Object(Doctrine\RST\Builder\ParseQueue))
  #12 vendor/doctrine/rst-parser/lib/Builder.php(157): Doctrine\RST\Builder->parse('/Users/javier/w...
  ', '/Users/javier/w...', Object(Doctrine\RST\Builder\ParseQueue))
  #13 docs-builder/src/DocBuilder.php(26): Doctrine\RST\Builder->build('/Users/javier/w...', '/Users/javi
  er/w...')
  #14 src/Command/BuildBundlesDocCommand.php(187): SymfonyDocsBuilder\DocBuilder->build(Object(Symfony
  DocsBuilder\BuildConfig))
  #15 src/Command/BuildBundlesDocCommand.php(79): App\Command\BuildBundlesDocCommand->buildDoc(Object(
  App\Entity\Bundle), '3.x')
  #16 vendor/symfony/console/Command/Command.php(256): App\Command\BuildBundlesDocCommand->execute(Obj
  ect(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
  #17 vendor/symfony/console/Application.php(989): Symfony\Component\Console\Command\Command->run(Obje
  ct(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
  #18 vendor/symfony/framework-bundle/Console/Application.php(96): Symfony\Component\Console\Applicati
  on->doRunCommand(Object(App\Command\BuildBundlesDocCommand), Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Comp
  onent\Console\Output\ConsoleOutput))
  #19 vendor/symfony/console/Application.php(290): Symfony\Bundle\FrameworkBundle\Console\Application-
  >doRunCommand(Object(App\Command\BuildBundlesDocCommand), Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Compone
  nt\Console\Output\ConsoleOutput))
  #20 vendor/symfony/framework-bundle/Console/Application.php(82): Symfony\Component\Console\Applicati
  on->doRun(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
  #21 vendor/symfony/console/Application.php(166): Symfony\Bundle\FrameworkBundle\Console\Application-
  >doRun(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
  #22 bin/console(43): Symfony\Component\Console\Application->run(Object(Symfony\Component\Console\Inp
  ut\ArgvInput))
  #23 {main}

The progress bar for the rendering process does not have a maximum - this should be fixed.

In this file: https://github.com/sonata-project/SonataAdminBundle/blob/3.x/docs/reference/security.rst there's this table:

The role name will be based on the name of your admin service.

========================   ======================================================
app.admin.foo              ROLE_APP_ADMIN_FOO_{PERMISSION}
my.blog.admin.foo_bar      ROLE_MY_BLOG_ADMIN_FOO_BAR_{PERMISSION}
App\\Admin\\FooAdmin       ROLE_APP\\ADMIN\\FOOADMIN_{PERMISSION}
========================   ======================================================

This is correctly parsed by Sphinx:

But with docs-builder, the table is not parsed and I see this error message:

/!\ Malformed table:

app.admin.foo | ROLE_APP_ADMIN_FOO_{PERMISSION}
my.blog.admin.foo_bar | ROLE_MY_BLOG_ADMIN_FOO_BAR_{PERMISSION}
App\\Admin\\FooAdmin | ROLE_APP\\ADMIN\\FOOADMIN_{PERMISSION}

Tables without heads are uncommon, but I wouldn't consider this an edge-case. Thanks!

namespace should be changed from SymfonyDocs to SymfonyDocsBuilder

In EasyAdmin docs we have the following in https://github.com/EasyCorp/EasyAdminBundle/blob/master/doc/fields.rst

Design Options
~~~~~~~~~~~~~~

::

    TextField::new('firstName', 'Name')
        // CSS class/classes are applied to the field contents (in the 'index' page)
        // or to the row that wraps the contents (in the 'detail', 'edit' and 'new' pages)

        // use this method to add new classes to the ones applied by EasyAdmin
        ->addCssClass('text-large text-bold')
        // use this other method if you want to remove any CSS class added by EasyAdmin
        ->setCssClass('text-large text-bold')

        // this defines the Twig template used to render this field in 'index' and 'detail' pages
        // (this is not used in the 'edit'/'new' pages because they use Symfony Forms themes)
        ->setTemplatePath('admin/fields/my_template.html.twig')

        // only applied to 'index' page. Useful for example to right-align numbers
        ->setTextAlign('right')

Formatting Options
~~~~~~~~~~~~~~~~~~

[...]

In current symfony.com it's correctly displayed as a code block:

However, docs-builder parses it as a blockquote (don't mind the design of the new doc, it's still unstyled):

symfony/symfony-docs#11032

symfony/symfony-docs#11030

maybe it's time to use symfony's DI, let's try it :)

see weaverryan/symfony-docs#11

See: https://github.com/weaverryan/docs-builder/pull/2/files#r245185858

Basically, once/if/hopefully when doctrine/rst-parser#89 is merged, we can update our code to simplify things.

Also, to speed things up, we could:

A) Collect all of the links, but not actually test them
B) Once we have them all, test the links but in parallel (e.g. maybe 5 at a time).

This would also allow us to have a reliable progress bar.

• Error if there is an .rst file that was never included in a toctree
• Ability to check external link for validity (2xx status code). Sphinx has this ability.
• Run php-cs-fixer on all code blocks

While generating Symfony Docs I found this error:

Unknown directive: "contents" in "testing" for line ".. contents::"

It's because in this file --> https://raw.githubusercontent.com/symfony/symfony-docs/4.4/testing.rst

we have things like this:

.. contents::
    :local:
    :depth: 1

I didn't know this directive. Apparently, it's used to add TOCs in the middle of some doc with the headings of the sections below this directive (http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents).

So, should we add support for this directive (which is used very rarely in our docs) or should we reword our docs to remove it? Thanks.

code-block:: terminal is highlighted like this:

We need the "prompt" ($ in Linux and macOS and C:\> in Windows) to be marked differently. This way we can apply different CSS styles to it and make it non-selectable by users (important when copying commands).

Today we do this using some ugly JS/CSS hacks ... but thanks to the new RST parser we could do this in PHP while building docs. It's similar to this -> https://github.com/weaverryan/docs-builder/pull/41/files

We could use hljs-prompt as the CSS class of this new element. Any volunteer to take care of this? Thanks!

Versioning is very important for Symfony Docs. Each doc page shows a version selector to read the same page for other Symfony versions. Most of the times this is trivial because the article maintains the slug/name and the path.

However, it's common to move contents in some versions. We have a file (https://github.com/symfony/symfony-docs/blob/master/_build/redirection_map) which maps old_path -> new_path ... so, for a given doc path, we can look up for the same path in older versions and if it doesn't exist, do a reverse lookup in that file to see if it had a different path in earlier versions.

Then, each doc item would include something like this:

"versions": {
  "2.0": "/something/foo",
  "2.1": "/something/foo",
  "2.2": "/something/foo",
  "...": "...",
  "2.7": "/new_something/foo",
  "2.8": "/new_something/foo",
  "...": "...",
  "4.0": "/new_something_new/bar",
  "4.1": "/new_something_new/bar",
  "master": "/new_something_new/bar",
}

This reverse lookup would be too expensive to do it when rendering the docs on the website, so it could be performed during the doc building process.

see weaverryan/symfony-docs#8

In Symfony Docs we use includes with placeholders.

E.g. this file -> https://raw.githubusercontent.com/symfony/symfony-docs/5.x/reference/forms/types/choice.rst includes things like this:

compound
~~~~~~~~

**type**: ``boolean`` **default**: same value as ``expanded`` option

This option specifies if a form is compound. The value is by default
overridden by the value of the ``expanded`` option.

.. include:: /reference/forms/types/options/empty_data.rst.inc
    :end-before: DEFAULT_PLACEHOLDER

The included file is this one: https://github.com/symfony/symfony-docs/blob/5.x/reference/forms/types/options/empty_data.rst.inc which includes the DEFAULT_PLACEHOLDER string.

However, the new builder doesn't support it and it's displayed like this:

Should we support this feature in this builder?

JSON generation process is not smart enough to realize that it doesn't need to rebuild everything.

It should be as simple as: if you can't find an Environment for a file (or maybe there is a better way to know if it was parsed, like using the ParseQueue, which has the list of files that needed to be parsed), then skip - the JSON should still be there and should still be up to date (I suppose we could throw an error if we find that the JSON file is missing for some reason)

see weaverryan/symfony-docs#18

See #102

In this page: https://symfony.com/doc/current/bundles/EasyAdminBundle/index.html

The TOC source code looks like this:

<div class="toctree-wrapper compound">
<ul>
<li class="..."><a class="..." href="dashboards.html">Dashboards</a></li>
<li class="..."><a class="..." href="crud.html">CRUD Controllers</a></li>
<li class="..."><a class="..." href="design.html">Design</a></li>
<li class="..."><a class="..." href="fields.html">Fields</a></li>
<li class="..."><a class="..." href="filters.html">Filters</a></li>
<li class="..."><a class="..." href="actions.html">Actions</a></li>
<li class="..."><a class="..." href="security.html">Security</a></li>
<li class="..."><a class="..." href="events.html">Events</a></li>
<li class="..."><a class="..." href="upgrade.html">Upgrading from EasyAdmin 2 to EasyAdmin 3</a></li>
</ul>
</div>

But in the new RST parser, it looks like this:

<div class="toctree-wrapper compound">
<ul>
<li><a href="dashboards.html#dashboards">Dashboards</a></li>
<li><a href="crud.html#crud-controllers">CRUD Controllers</a></li>
<li><a href="design.html#design">Design</a></li>
<li><a href="fields.html#fields">Fields</a></li>
<li><a href="filters.html#filters">Filters</a></li>
<li><a href="actions.html#actions">Actions</a></li>
<li><a href="security.html#security">Security</a></li>
<li><a href="events.html#events">Events</a></li>
<li><a href="upgrade.html#upgrading-from-easyadmin-2-to-easyadmin-3">Upgrading from EasyAdmin 2 to EasyAdmin 3</a></li>
</ul>
</div>

All entries have an unnecessary page fragment (e.g. dashboards.html#dashboards instead of just dashboards.html).

The source code (see https://raw.githubusercontent.com/EasyCorp/EasyAdminBundle/master/doc/index.rst): is just:

EasyAdmin
=========

[...]

Table of Contents
-----------------

.. toctree::
    :maxdepth: 1

    dashboards
    crud
    design
    fields
    filters
    actions
    security
    events
    upgrade

[...]

When parsing a specific book I need to add Step 0, Step 1, etc. to <h1> headings of each article and also, inside each article, I need to number <h2> headings as 0.0', 0.1', 0.2, ..., 1.0, 1.1, 1.2, etc.

I created a TitleNodeRenderer but I can't get the name of the file being parsed, which is the one that contains both the book name and the chapter number. I wish we had a context object with all the essential parsing information available everywhere to unlock powerful features.

Thanks!

In this page: https://raw.githubusercontent.com/symfony/symfony-docs/4.3/testing.rst

We have this sidebar directive:

.. sidebar:: More about the ``request()`` Method:

    The full signature of the ``request()`` method is::

    [...]

The parser doesn't parse request() inside the sidebar title as a <code> element:

In this article -> https://raw.githubusercontent.com/EasyCorp/EasyAdminBundle/master/doc/fields.rst we have this:

Next, create the template used to render the field in the ``index`` and ``detail``
:ref:`CRUD pages <crud-pages>`. The template can use any `Twig templating features`_
and the following variables:

Everything is correctly parsed, but there's a minor issue. The generated HTML is:

<p>Next, create the template used to render the field in the <code>index</code> and <code>detail</code><a href="crud.html#crud-pages" class="reference internal">CRUD pages</a>. The template can use any <a href="https://twig.symfony.com/doc/3.x/" class="reference external">Twig templating features</a>

The problem is that there isn't a white space between <code>detail</code> and the following <a> reference. The missing white space is needed to avoid this:

In this file -> https://github.com/EasyCorp/EasyAdminBundle/blob/master/doc/events.rst we have this:

All events are triggered using objects instead of event names defined as strings
(as recommended since Symfony 4.3). They are defined under the
``EasyCorp\Bundle\EasyAdminBundle\Event\`` namespace:

* Events related to Doctrine entities:

  * ``AfterEntityBuiltEvent``
  * ``AfterEntityDeletedEvent``
  * ``AfterEntityPersistedEvent``
  * ``AfterEntityUpdatedEvent``
  * ``BeforeEntityDeletedEvent``
  * ``BeforeEntityPersistedEvent``
  * ``BeforeEntityUpdatedEvent``

* Events related to resource admins:

  * ``AfterCrudActionEvent``
  * ``BeforeCrudActionEvent``

This is the right way to create nested lists for Sphinx (so I guess it's the right way in RST in general too). That includes the blank lines after the first level bullets. In the current parser it works OK, but in the new parser it generates this wrong HTML:

As you can see, the nested <ul> is outside of the <li>, but it should be inside of it.