TYPO3-Documentation / TYPO3-Documentation/render-guides

Use `Documentation` as a default `--config` option setting

Open
#486 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement help wanted
Dominant language
HTML
Stars
13
Forks
19
Avg merge
2d 17h
Merged PRs (30d)
60

Description

In #421 I tried to adjust guides and render-guides so that it would use --config=Documentation as a default.

Since this idea was part of #421 where it didn't belong, and I failed with my approach, we may address this at a later time.

Description:

render-guides/packages/guides-cli/bin/guides does a very early interpretation of the "config" attribute:
https://github.com/phpDocumentor/guides/blob/main/packages/guides-cli/bin/guides#L54

That means, I'd have to inject fetching a default configuration (based on the path that is to be rendered) at this place.

However, the directory to render is calculated much later on (guides defines it as "docs", render-guides defines it as "Documentation" in a decorator).

So:

  • In the guides binary, I can influence additional loading of a guides.xml - but I cannot get the default "Documentation" render directory, because that is performed AFTER the guides.xml loading.
  • In our render-guides Decorator I can get the proper render directory, but I can no longer inject a guides.xml file (because the container is already built with the XML specifications as part of guides).

I could fetch a default "config" option in the case that a Directory is specified:

vendor/bin/guides Documentation

but I could not get the "right" directory name ("Documentation/") if I would call the binary just via:

vendor/bin/guides

So I think we'll need to retain '--config' as a mandatory argument.

For overview, current behavior:

vendor/bin/guides
# -> Renders "/Documentation", loads "/guides.xml"

vendor/bin/guides Documentation
# -> Renders "/Documentation", loads "/guides.xml"

vendor/bin/guides --config=Documentation
# -> Renders "/Documentation", loads "/Documentation/guides.xml" and "/guides.xml"

vendor/bin/guides --config=Documentation Documentation
# -> Renders "/Documentation", loads "/Documentation/guides.xml" and "/guides.xml"

My goal would be to make all four commands do the same: Render "Documentation", load "Documentation/guides.xml" and load "/guides.xml".

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with render-guides/packages/guides-cli/bin/guides, especially its early config handling, then inspect the render-guides Decorator where the default render directory is selected. Compare all four documented command forms and define done as each rendering Documentation while loading both Documentation/guides.xml and the root guides.xml.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
cli, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.