v0.3.0

Stabilize and improve

In this new release of guides we have been focusing on the stabilization of the libraries and fixed a large number of bugs and adding missing features that were supported in sphinx. In colaboration with the Typo3 documentation team, and collaborators from doctrine and symfony we have been testing the library on real world documentation stacks.

Please not that we do not guarantee any backward compatibility in the current state, for normal usage you should not have many issues to solve when upgrading.

Guides cli

There has been done quite some work on the usability of the cli tool we provide. To make it easier to extend to also
to make it easier in use. Most important changes in the arguments we removed from the run command. New way to execute
the guides cli is:

    vendor/bin/guides --output=test <input>

We removed the mandatory output argument and made it an option, you can specify the output directory now in the
guides.xml, or use the option in cli.

• [FEATURE] Add option input-file to render a specific file by @linawolf in #599
• [FEATURE] show progressbar and output only when not quite by @jaapio in #648
• [!!!][TASK] Make output an option instead of argument by @linawolf in #650
• [DOCS] Clarify parameter usage for the "guides" binary] by @garvinhicking in #680
• [FEATURE] allow setting working dir by @jaapio in #691

Guides code

New added component to the guides family is the guides-code component. This component is used to highlight code blocks
in the documentation. This component is used by the guides cli and can be used standalone.

Guides core

Rendering has been revisited, previously the render context had connections with services and there was a
connection between the template engine and node renderers. This has been removed and the render context is now
a valueobject.

• !!![TASK] Remove all services from render context by @jaapio in #645

To speed up the renderer significantly we have added a cache for the node renderers. This cache is used to store
the node renderers for a specific node type. This cache is only used at runtime and is not persisted.

• Cache matching node renderers by @wouterj in #784

As a proof of concept we have added a latex renderer to the guides core. This renderer is not yet fully functional,
but it shows how to add a new renderer to the guides core.

• !!![FEATURE] enable basic latex rendering by @jaapio in #654

New in this version is the support for markdown files. This is a basic support, but it is possible to use markdown
files in your documentation, however concepts like table of contents and menu's are not yet supported.

• [FEATURE] Enable basic Markdown files by @linawolf in #640

Menu handling has been improved, the menus are now better handling the max depth. And collection of the menu items
have been improved.

Other notable changes:

• [BUGFIX] Fix parsing and rendering of code-block with line numbers by @linawolf in #685
• [FEATURE] make it easier to configure templates. by @jaapio in #663
• [BUGFIX] Let Image sources respect relative and absolute links config… by @linawolf in #695
• [BUGFIX] Allow tabs in line indentations by @linawolf in #745

ReStructuredText

We have done a lot of improvements in the way references are handled. This solves a lot of issues with references.

• [BUGFIX] Rename textrole template by @linawolf in #744
• [FEATURE] Introduce Toctree caption by @linawolf in #704
• [FEATURE] Display Caption of contents menu by @linawolf in #694
• [BUGFIX] Do not use local resolvers for interlinks by @linawolf in #701
• [BUGFIX] Allow angled content in references by @linawolf in #711
• [TASK] Improve reference warnings by @linawolf in #720
• [TASK] Split Anchor link resolvers by @linawolf in #719
• !!![TASK] Improve Reference parsing by @linawolf in #798
• !!![TASK] Warn only once when a reference cannot be resolved by @linawolf in #797
• !!![TASK] Restructure Menu handling by @linawolf in #799
• [BUGFIX] Generate Warning when menu entry was not found by @linawolf in #804

Added directives:

• [FEATURE] Introduce only directive by @linawolf in #698
• [FEATURE] Introduce confval directive by @linawolf in #651
• [FEATURE] Introduce option directive by @linawolf in #636
• [FEATURE] add configuration block directive by @jaapio in #795
• [FEATURE] Support emphasize-lines in code-block directive by @linawolf in #690

Other notable changes:

• [FEATURE] Make relative, absolute and links relative to a base URL possible by @linawolf in #614
• [FEATURE] Support Hyperlinks to local pages in rst and md by @linawolf in #747
• [FIX]: be more strict on anonymous links by @jaapio in #628

General improvements

• Allow Symfony 7 by @greg0ire in #793

• [CI] start building on php 8.3 by @jaapio in #713

• Fix: allow absolute image urls by @jaapio in #626

• Allow setting a default language for literal blocks by @wouterj in #608

New Contributors

• @brotkrueml made their first contribution in #662
• @garvinhicking made their first contribution in #680

Full Changelog: 0.2.0...0.3.0