TYPO3-Documentation / TYPO3-Documentation/render-guides
Use `Documentation` as a default `--config` option setting
Nobody has claimed this yet.
- 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
guidesbinary, 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-guidesDecorator 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 ofguides).
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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