Code Monkey home page Code Monkey logo

guides's Introduction

License: MIT Qa workflow Packagist Version Packagist Pre Release Version Downloads

phpDocumentor

What is phpDocumentor?

phpDocumentor stands as the de-facto documentation tool for PHP projects, offering a robust solution for generating comprehensive documentation effortlessly. By analyzing your PHP source code and DocBlock comments, phpDocumentor generates a complete set of API documentation, making it an indispensable tool for developers striving for clear and well-documented codebases.

Beyond its prowess in API documentation, phpDocumentor goes further by providing additional features. It is equipped with the ability to create UML diagrams, making it a versatile tool for visualizing code structure. Additionally, phpDocumentor offers a full-featured markup language parser, supporting both RestructuredText and Markdown syntax. This flexibility allows you to document your project using the markup language that best suits your preferences.

A notable feature of phpDocumentor is its capability to include parts of your API documentation directly into your RestructuredText documentation. This integration ensures that your documentation and code remain in sync, saving you time and effort in maintaining accurate and up-to-date project documentation.

Inspired by its predecessors, phpDocumentor 1 and JavaDoc, phpDocumentor continues to innovate, staying up-to-date with the latest technologies and PHP language features. This commitment ensures that developers have access to the best possible documentation experience, aligning with modern development practices.

In this guide, we will explore the various features of phpDocumentor, from its core functionality in generating API documentation to its advanced capabilities in parsing markup languages. Whether you're a beginner or an experienced developer, phpDocumentor is your ally in creating well-documented, maintainable, and understandable PHP projects.

phpDocumentor v3 (Stable)

v3 is the latest stable release.

Documentation

For more detailed information, you can check our online documentation at https://docs.phpdoc.org/.

Features

phpDocumentor supports the following:

  • PHP 7.0+ compatible, full support for Namespaces, Closures and more are provided.
  • Docblock over types, docblocks can be more explicit about types not all formats are supported by native php.
  • Shows any tag, some tags add additional functionality to phpDocumentor (such as @link).
  • Low memory usage, peak memory usage for small projects is less than 20MB, medium projects 40MB, and large frameworks 100MB.
  • Incremental parsing, if you kept the Structure file from a previous run, you get an additional performance boost of up to 80% on top of the mentioned processing speed increase above.
  • Easy template building, if you want to make a branding you only have to call 1 task and edit 3 files.
  • Two-step process, phpDocumentor first generates a cache with your application structure before creating the output. If you'd like you can use that to power your own tools or formatters!
  • Generics support, with more static analysis in php types have become more complex. phpDocumentor understand these types. And will render them as first class types.

Installation

PhpDocumentor requires PHP 8.1 or higher to run. However, code of earlier PHP versions can be analyzed.

All templates provided with phpDocumentor have support for Class diagrams based on the read code base. This will require the application [PlantUml] to be installed on the machine running phpDocumentor. Rendering the class diagrams using [PlantUml] is optional, and warnings about missing [PlantUml] can be ignored. However, your documentation will contain some dead links in this case. Class diagram will be created with option --setting=graphs.enabled=true.

There are 4 ways to install phpDocumentor:

  1. Using phive (recommended)
  2. Using the PHAR (manual install)
  3. Via Docker
  4. Via Composer

Using Phive

$ phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42

For more information about phive have a look at their website. Now you have phpDocumentor installed, it can be executed like this:

php tools/phpDocumentor

Using the PHAR

  1. Download the phar file from https://github.com/phpDocumentor/phpDocumentor/releases
  2. You can execute the phar like this: php phpDocumentor.phar

Via Docker

  1. $ docker pull phpdoc/phpdoc
  2. $ docker run --rm -v $(pwd):/data phpdoc/phpdoc

Via Composer (not recommended)

But wait? What about composer?

Ah, you discovered our secret. There is a phpdocumentor composer package that you can use to install phpDocumentor.

However: phpDocumentor is a complex application, and its libraries are used in countless other libraries and applications (2 of our libraries have more than 150 million downloads each); and this means that the chances for a conflict between one of our dependencies and yours is high. And when I say high, it is really high.

So, because of the above: we do not endorse nor actively support installing phpDocumentor using Composer.

How to use phpDocumentor?

The easiest way to run phpDocumentor is by running the following command:

$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>

This command will parse the source code provided using the -d argument and output it to the folder indicated by the -t argument.

phpDocumentor supports a whole range of options to configure the output of your documentation. You can execute the following command, or check our website, for a more detailed listing of available command-line options.

$ phpdoc run -h

Configuration file(s)

phpDocumentor also supports the use of configuration files (named phpdoc.xml or phpdoc.dist.xml by default). Please consult the documentation to see the format and supported options.

Nightly builds

PhpDocumentor doesn't have nightly releases. However, during each pipeline a phar artifact is built. If you want to test the bleeding edge version of phpDocumentor, have a look in the actions section of this repository. Each successful QA workflow has an Artifacts section at the bottom with the phar artifact built.

Contact

Reaching out to us is easy, and can be done with:

guides's People

Contributors

brotkrueml avatar dependabot[bot] avatar derrabus avatar floriant03 avatar garvinhicking avatar github-actions[bot] avatar greg0ire avatar jaapio avatar linawolf avatar mabolek avatar mvriel avatar tomwarwick avatar wouterj avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar avatar avatar avatar

Forkers

wouterj stof linawolf davidbruchmann mabolek tomwarwick derrabus sarahmccarthy123 greg0ire floriant03 geraldib brotkrueml garvinhicking kaystrobach liercesantos

guides's Issues

Add progress bar to cli

When executing the cli app, there is no output shown, introduce a progress bar to show some output to the user.

Support Sphinx's caption option on the code-block node

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-option-code-block-caption

Sphinx allows to add a caption to a code block (e.g. a filename). We use this in some parts of the Symfony documentation and it would be great if we can add support for it in this library.

Failing test in Symfony's docs-builder repository

https://github.com/wouterj/symfony-docs-guides/actions/runs/4713936115/jobs/8359959701

4) SymfonyDocsBuilder\Tests\HtmlIntegrationTest::testBlocks with data set "code-blocks/code-caption.rst" ('/home/runner/work/symfony-doc...on.rst', '/home/runner/work/symfony-doc...n.html')
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'<div translate="no" data-loc="1" class="notranslate codeblock codeblock-length-sm codeblock-php codeblock-has-caption">\n
-<div class="codeblock-caption">config/routes.php</div>\n
+'<div translate="no" data-loc="1" class="notranslate codeblock codeblock-length-sm codeblock-php">\n
 <div class="codeblock-scroll">\n
 <pre class="codeblock-lines">1</pre>\n
 <pre class="codeblock-code"><code><span class="hljs-variable"><span class="hljs-variable-other-marker">$</span>foo</span>=<span class="hljs-string">'bar'</span>;</code></pre>\n
 </div>\n
 </div>\n
-<div translate="no" data-loc="1" class="notranslate codeblock codeblock-length-sm codeblock-php codeblock-has-caption hide">\n
-<div class="codeblock-caption">config/routes.php</div>\n
+<div translate="no" data-loc="1" class="notranslate codeblock codeblock-length-sm codeblock-php">\n
 <div class="codeblock-scroll">\n
 <pre class="codeblock-lines">1</pre>\n
 <pre class="codeblock-code"><code><span class="hljs-variable"><span class="hljs-variable-other-marker">$</span>foo</span>=<span class="hljs-string">'bar'</span>;</code></pre>\n

/home/runner/work/symfony-docs-guides/symfony-docs-guides/lib/docs-builder/tests/integration/HtmlIntegrationTest.php:29```

</details>

Drop PHP 7.2 and 7.3 Support from guides?

In the main composer.json we are requiring php above 7.4, and tests are run for PHP 7.4 and 8.0 as far as I can tell.
packages/guides/composer.json however still allows PHP 7.2. I would really like to use typed properties and as this version is also not covered by tests anymore can we drop it?

Text roles and whitespace control

Contrary to body elements, preserving original whitespace is important for inline elements.

Some tests on the Symfony test repository are failing because of missing spaces before an inline <code> element, as well as new lines after a </code> tag. (EDIT: missing space before is probably due to a bit too heavy whitespace removal by the tests)

An inline newline is converted to a space in HTML, which works out most of the time but not when e.g. you put an inline literal before a final stop or comma (like at the end of the test case below).

See e.g. this test output:

3) SymfonyDocsBuilder\Tests\HtmlIntegrationTest::testBlocks with data set "text-roles/reference-and-code.rst" ('/home/runner/work/symfony-doc...de.rst', '/home/runner/work/symfony-doc...e.html')
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'<p>Next, create the template used to render the field in the<code translate="no" class="notranslate">index</code>and<code translate="no" class="notranslate">detail</code>\n
-<a href="https://symfony.com/doc/current/bundles/EasyAdminBundle/crud.html" class="reference internal">CRUD pages</a>.</p>\n
+'<p>Next, create the template used to render the field in the<code translate="no" class="notranslate">index</code>\n
+and<code translate="no" class="notranslate">detail</code><a href="https://symfony.com/doc/current/bundles/EasyAdminBundle/crud.html" class="reference internal">CRUD pages</a>\n
+.</p>\n
 <p>More about CRUD pages.</p>'

/home/runner/work/symfony-docs-guides/symfony-docs-guides/lib/docs-builder/tests/integration/HtmlIntegrationTest.php:29```

Spanparser is not working 100% correctly 

          Not sure if it's 100% related to this one, but when rendering the Symfony docs on this branch (rebased on #252) there are some invalidly detected references.

Examples:

``choice``: renders one, two (default) or three select inputs (hour, minute,
everything after : is detected as a single reference (there is no reference on the line).

When using different values for `model_timezone`_ and ``view_timezone``,
this whole line is detected as a single reference (instead of only model_timezone)

**type**: ``integer`` **default**: Locale-specific (usually around ``3``)
Locale-specific (usually around ``3``) is detected as reference

Securing by an Expression
gives an error "invalid cross reference: ecuring by an Expression"

Other than this, it seems to work flawless on the Symfony docs! :)

Originally posted by @wouterj in #233 (comment)

Add ref role implementation

https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#the-ref-role

Currently, the DocResolver claims to be able to handle both :ref: and :doc: roles, but the implementation only implements :doc: roles.

:ref: allows you to reference so-called internal hyperlink targets inside the project (not necessarily the current document). We use this a lot in the Symfony documentation to link users to specific sections of another page.
However, the current ref implementation works like doc: it allows you to link to documents inside the project.

In order to properly support the ref role, the Metas class must be refactored a bit. It currently doesn't store internal hyperlink targets in a flat map, which will be required for the RefResolver.

If this is not yet part of the roadmap of this package, I'm happy to start the contribution of this feature. I mainly created this issue to see if I'm missing something here and avoid duplicate work.

Implement all docutils admonitions + handle admonition arguments correctly

We currently do not support all admonitions, given it is easy to add support (by extending AbstractAdmonitionDirective) I would say we should add support for it.

I've created a branch that updates the tests, which can be used as a base when working on this issue: main...wouterj:guides:admonitions

In here you can also find some other admonition related tests that need to be fixed:

  • The generic .. admonition:: directives behaves different from all note/warning/caution/hint/etc directives concerning it's argument.
    For all admonitions, the text directly following the directive is considered the first paragraph of a directive: d0cc00a
    For the generic admonition, this "argument" is treated as the title and is also used to generate a class name: 9be2145
  • The version changeset directives (versionadded/versionchanged/deprecated) are not implemented as admonitions but are their own "VersionChange" directive (with a related VersionChangeNode). They are rendered a bit differently and require an argument (the changed version): 1f54b62

Support nested lists

I think we still have a problem here and several skipped tests, for example
tests/Integration/tests/numbered-lists

Improve Buffer class

Right now we have a number of locations using the buffer class to collect lines from the documents to parse them as blocks. These blocks are always indented. When consuming this buffer we need to remove the initial indentation of the block to be able to process the lines are normal lines.

We want the buffer to be responsible for this un-indenting part. To centralize the way we are doing this. The complexity here is that the indentation of a block may defer per situation. and can be something between 2 or PHP_MAX_INT spaces.

Locations where to do this improvement:

This method removes the indenting. Based on the first line of a block.
\phpDocumentor\Guides\RestructuredText\Parser\Productions\BlockQuoteRule::normalizeLines

Here I do something simular for lists
packages/guides-restructured-text/src/RestructuredText/Parser/Productions/ListRule.php:107
packages/guides-restructured-text/src/RestructuredText/Parser/Productions/EnumeratedListRule.php:109
Definition lists: packages/guides-restructured-text/src/RestructuredText/Parser/Productions/DefinitionListRule.php:99

See #225 for the original discussion.

Undefined array key when project['title'] is not defined

Wehn the title attribute in the project tag of the guides.xml file is not available, then the following warning is thrown:

PHP Warning: Undefined array key "title" in vendor/phpdocumentor/guides/src/DependencyInjection/GuidesExtension.php on line 144

Support the `class` option for directives

Per https://docutils.sourceforge.io/docs/ref/rst/directives.html#common-options , any directive with content allows a class option that adds custom classes to the directive's DOM element.

We rely on this in some parts of the Symfony documentation, it would great to add support for this option.

Failing test on Symfony's docs-builder tests

https://github.com/wouterj/symfony-docs-guides/actions/runs/4713936115/jobs/8359959701

5) SymfonyDocsBuilder\Tests\HtmlIntegrationTest::testBlocks with data set "code-blocks/terminal.rst" ('/home/runner/work/symfony-doc...al.rst', '/home/runner/work/symfony-doc...l.html')
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
 <span class="hljs-comment"># Civilization for DOS - my first computer game!</span></code></pre>\n
 </div>\n
 </div>\n
-<div translate="no" data-loc="1" class="notranslate codeblock codeblock-length-sm codeblock-terminal codeblock-bash hide">\n
+<div translate="no" data-loc="1" class="notranslate codeblock codeblock-length-sm codeblock-terminal codeblock-bash">\n
 <div class="codeblock-scroll">\n
 <pre class="codeblock-lines">1</pre>\n
 <pre class="codeblock-code"><code><span class="hljs-prompt">$</span>git branch -D sessions-in-db ||<span class="hljs-literal">true</span></code></pre>\n
 </div>\n
 </div>'

/home/runner/work/symfony-docs-guides/symfony-docs-guides/lib/docs-builder/tests/integration/HtmlIntegrationTest.php:29```

</details>

"emphasize-lines" in "code-block" directive not considered

In the following example:

..  code-block:: python
    :emphasize-lines: 3,5

    def some_function():
        interesting = False
        print('This line is highlighted.')
        print('This one is not...')
        print('...but this one is.')

does not emphasize the lines.

In the CodeNode there is also no property for this:

object(phpDocumentor\Guides\Nodes\CodeNode)#2467 (6) {
  ["classes":protected]=>
  array(0) {
  }
  ["options":protected]=>
  array(0) {
  }
  ["value":protected]=>
  string(148) "def some_function():
    interesting = False
    print('This line is highlighted.')
    print('This one is not...')
    print('...but this one is.')"
  ["startingLineNumber":"phpDocumentor\Guides\Nodes\CodeNode":private]=>
  NULL
  ["caption":"phpDocumentor\Guides\Nodes\CodeNode":private]=>
  NULL
  ["language":protected]=>
  string(6) "python"
}

Using lineno-start on code-block directive throws error

Using this code block:

..  code-block:: ruby
    :lineno-start: 10

    Some more Ruby code, with line numbering starting at 10.

The following warning is triggered:

/opt/project/vendor/phpdocumentor/guides-restructured-text/src/RestructuredText/Directives/CodeBlockDirective.php:87
Object of class phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption could not be converted to int

Relative links no longer working

Since #480 , building the Doctrine ORM docs produces a lot of warnings:

[2023-07-09T14:28:52.000742+00:00] app.WARNING: Reference dql-user-defined-functions could not be resolved in cookbook/advanced-field-value-conversion-using-custom-mapping-types [] []
[2023-07-09T14:28:52.039679+00:00] app.WARNING: Reference ../reference/native-sql could not be resolved in cookbook/dql-user-defined-functions [] []
[2023-07-09T14:28:52.266874+00:00] app.WARNING: Reference ../reference/tools could not be resolved in reference/advanced-configuration [] []
[2023-07-09T14:28:52.294241+00:00] app.WARNING: Reference change-tracking-policies could not be resolved in reference/annotations-reference [] []
[2023-07-09T14:28:52.318856+00:00] app.WARNING: Reference namingstrategy could not be resolved in reference/annotations-reference [] []
[2023-07-09T14:28:52.332561+00:00] app.WARNING: Reference inheritance-mapping could not be resolved in reference/annotations-reference [] []
[2023-07-09T14:28:52.371021+00:00] app.WARNING: Reference /reference/inheritance-mapping could not be resolved in reference/architecture [] []
[2023-07-09T14:28:52.382536+00:00] app.WARNING: Reference unitofwork-associations could not be resolved in reference/association-mapping [] []
[2023-07-09T14:28:52.448356+00:00] app.WARNING: Reference change-tracking-policies could not be resolved in reference/attributes-reference [] []
[2023-07-09T14:28:52.471608+00:00] app.WARNING: Reference namingstrategy could not be resolved in reference/attributes-reference [] []
[2023-07-09T14:28:52.487268+00:00] app.WARNING: Reference inheritance-mapping could not be resolved in reference/attributes-reference [] []
[2023-07-09T14:28:52.515394+00:00] app.WARNING: Reference association-mapping could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.517150+00:00] app.WARNING: Reference attributes-reference could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.517443+00:00] app.WARNING: Reference xml-mapping could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.517724+00:00] app.WARNING: Reference php-mapping could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.517994+00:00] app.WARNING: Reference annotations-reference could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.518598+00:00] app.WARNING: Reference yaml-mapping could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.530743+00:00] app.WARNING: Reference tools could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.540732+00:00] app.WARNING: Reference typedfieldmapper could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.549471+00:00] app.WARNING: Reference ../cookbook/custom-mapping-types could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.550768+00:00] app.WARNING: Reference ../cookbook/working-with-datetime could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.558671+00:00] app.WARNING: Reference ../tutorials/composite-primary-keys could not be resolved in reference/basic-mapping [] []
[2023-07-09T14:28:52.599000+00:00] app.WARNING: Reference /reference/advanced-configuration could not be resolved in reference/configuration [] []
[2023-07-09T14:28:52.600154+00:00] app.WARNING: Reference ../reference/tools could not be resolved in reference/configuration [] []
[2023-07-09T14:28:52.675498+00:00] app.WARNING: Reference /reference/batch-processing could not be resolved in reference/dql-doctrine-query-language [] []
[2023-07-09T14:28:52.719824+00:00] app.WARNING: Reference /tutorials/embeddables could not be resolved in reference/events [] []
[2023-07-09T14:28:52.769107+00:00] app.WARNING: Reference ../tutorials/composite-primary-keys could not be resolved in reference/faq [] []
[2023-07-09T14:28:52.772181+00:00] app.WARNING: Reference inheritance-mapping could not be resolved in reference/faq [] []
[2023-07-09T14:28:52.792793+00:00] app.WARNING: Reference ../tutorials/extra-lazy-associations could not be resolved in reference/improving-performance [] []
[2023-07-09T14:28:52.794328+00:00] app.WARNING: Reference /reference/best-practices could not be resolved in reference/improving-performance [] []
[2023-07-09T14:28:52.794956+00:00] app.WARNING: Reference change-tracking-policies could not be resolved in reference/improving-performance [] []
[2023-07-09T14:28:52.797706+00:00] app.WARNING: Reference /cookbook/resolve-target-entity-listener could not be resolved in reference/inheritance-mapping [] []
[2023-07-09T14:28:52.799499+00:00] app.WARNING: Reference /reference/limitations-and-known-issues could not be resolved in reference/inheritance-mapping [] []
[2023-07-09T14:28:52.812724+00:00] app.WARNING: Reference /reference/limitations-and-known-issues could not be resolved in reference/inheritance-mapping [] []
[2023-07-09T14:28:52.820413+00:00] app.WARNING: Reference /reference/configuration could not be resolved in reference/installation [] []
[2023-07-09T14:28:52.831672+00:00] app.WARNING: Reference /tutorials/override-field-association-mappings-in-subclasses could not be resolved in reference/limitations-and-known-issues [] []
[2023-07-09T14:28:52.835719+00:00] app.WARNING: Reference basic-mapping could not be resolved in reference/limitations-and-known-issues [] []
[2023-07-09T14:28:52.920358+00:00] app.WARNING: Reference faq could not be resolved in reference/query-builder [] []
[2023-07-09T14:28:53.051664+00:00] app.WARNING: Reference change-tracking-policies could not be resolved in reference/unitofwork [] []
[2023-07-09T14:28:53.060309+00:00] app.WARNING: Reference unitofwork-associations could not be resolved in reference/working-with-associations [] []
[2023-07-09T14:28:53.076708+00:00] app.WARNING: Reference working-with-objects could not be resolved in reference/working-with-associations [] []
[2023-07-09T14:28:53.137645+00:00] app.WARNING: Reference working-with-associations could not be resolved in reference/working-with-objects [] []
[2023-07-09T14:28:53.140195+00:00] app.WARNING: Reference dql-doctrine-query-language could not be resolved in reference/working-with-objects [] []
[2023-07-09T14:28:53.140618+00:00] app.WARNING: Reference query-builder could not be resolved in reference/working-with-objects [] []
[2023-07-09T14:28:53.141317+00:00] app.WARNING: Reference native-sql could not be resolved in reference/working-with-objects [] []
[2023-07-09T14:28:53.478732+00:00] app.WARNING: Reference getting-started could not be resolved in tutorials/getting-started-database [] []
[2023-07-09T14:28:53.478990+00:00] app.WARNING: Reference getting-started-models could not be resolved in tutorials/getting-started-database [] []
[2023-07-09T14:28:53.481349+00:00] app.WARNING: Reference getting-started could not be resolved in tutorials/getting-started-models [] []
[2023-07-09T14:28:53.481600+00:00] app.WARNING: Reference getting-started-database could not be resolved in tutorials/getting-started-models [] []
[2023-07-09T14:28:53.494913+00:00] app.WARNING: Reference ../reference/configuration could not be resolved in tutorials/getting-started [] []
[2023-07-09T14:28:53.496407+00:00] app.WARNING: Reference ../reference/tools could not be resolved in tutorials/getting-started [] []

It seems relative links can no longer be resolved. @wouterj can you please help with this? 🙏

Nested <UL> lists are not correctly parsed

When I use the following construct:

#. 1st level of nesting
    #. Second level of nesting
#. 1st level of nesting again

I expected the output to be a UL with a nested UL in the first LI.

However, when I do the above, I get a UL, with a nested DL and in that a nested UL in the first LI. This means that the output is semantically incorrect and double indented because of the DL.

To make it more interesting: when I add whitelines, suddenly I do not get a DL, but a blockquote around the nested UL :)

#. 1st level of nesting

    #. Second level of nesting

#. 1st level of nesting again

[GETTING-STARTED] Write contributions file

People who want to contribute to this project should have guidelines how to contribute.

As this is a mono repo split into separate repositories this might require some extra assistance.

  • make them aware about issues
  • creating new pr's
  • help with the make file setup

Underscores in the middle of text cause warnings

Input like

Some text EXT:css_styled_content/static/v6.2 causes warnings like

[2023-08-19T13:13:26.326444+00:00] app.WARNING: Reference EXT:css_styled_content/static/v6.2 could not be resolved in index [] []

RST `image` directive tries to load images from local, even if explicitly passed as absolute URLs

I am using https://pandoc.org (which, heck, I wish I knew it earlier) to generate rst from my markdown (and other) file formats.
This works like a charm.

However, there is a peculiarity in the PHPDocumentor Guides feature.
Whenever I generate a Guide using the rst file it generates img tags that look for the image source file on the local path. That of course causes the images to not load.

Example

  • In the rst you have:
|GitHub contributors|
// other content
.. |GitHub contributors| image:: https://img.shields.io/github/contributors/ORG/REPO
  • PHPDocumentor Guide HTML output:
<img src="guide/tukutoi-template-builder/https://img.shields.io/github/contributors/ORG/REPO">

It is self-explanatory why I cannot use local files here: the whole point of this badge is that it is dynamically generated by GitHub.

Can this be fixed somehow? I already tried to wrap my absolute URL in <> in the rst file, which did not help.
Perhaps some config attribute, or terminal command I am not aware of?

Anchors before a new section should replace the implicit section ID

Consider this rst document:

Section A
---------

.. _custom-id:

Section B
---------

It should contain 2 sections: Section A with (implicit) id section-a and Section B with (explicit) id custom-id.
Currently, this library adds an <a name="custom-id"></a> in front of Section B, but still keeps its implicit ID (section-b).

We should "collapse" an AnchorNode if it's directly followed by a SectionNode using a compiler pass (#221 implemented a similar logic for the .. class:: directive).

Guides: Links are not created within lists

Links within lists are not created.

Expected behavior

Links are expected to be created within the page.

Actual behavior

Links are not created.

Steps to reproduce the problem

  1. Create a document (guides/test/index.rst) like the example below:
Test
====

- `Link Foo`_
- `Link Bar`_

Link Foo
--------

Link Bar
--------
  1. Run the phpDocumentor.phar.
  2. The following warnings appear on the screen:
[warning] Generating guides is experimental, no BC guarantees are given, use at your own risk
[warning] Reference Link Foo could not be resolved in test/index
[warning] Reference Link Bar could not be resolved in test/index
  1. See on the generated page that links are not created.

Your environment

  • Version used: v3.4.3
  • Install method: phar
  • PHP version: 8.1
  • Operating system and version (e.g. Ubuntu 20.04, Windows 10): Ubuntu 22.04
  • Link to your project:
  • Attach code that is involved
  • ...

Base Template Example.

Could you please add the the guides a basic template is the same as the default template?
I like phpDoc, but I'd like to make some minor adjustments.
I found sunaoka / phpDocumentor3-template-ja which adjusts the headers to Japanese.
Thank you

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.