TYPO3: Unify Settings.cfg of TYPO3 Core documentation

[alexander-nitsche]

Having a look at the Settings.cfg of the TYPO3 system extensions there are some variants out there and i would like to find the one Settings.cfg which should be used and apply that to all extensions.

Let's take the rather new typo3/sysext/adminpanel/Documentation/Settings.cfg as starting point:

[general]
project     = Admin Panel
version     = master
release     = master
copyright   = 2021
description = This is the documentation of TYPO3's system extension 'adminpanel'.
              It displays a bar at the bottom of the screen on the frontend,
              from which you can access information per page.

[html_theme_options]
# Add 'Edit me on Github' button
github_branch             = master
github_repository         = typo3/typo3
path_to_documentation_dir = typo3/sysext/adminpanel/Documentation
# Show as related links
project_contact      =
project_discussions  =
project_home         = https://forge.typo3.org/projects/typo3cms-core
project_issues       = https://forge.typo3.org/projects/typo3cms-core/issues
project_repository   = https://github.com/typo3/typo3

[intersphinx_mapping]
h2document    = https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/
# t3coreapi     = https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/
# t3editors     = https://docs.typo3.org/m/typo3/tutorial-editors/master/en-us/
# t3extbasebook = https://docs.typo3.org/m/typo3/book-extbasefluid/master/en-us/Index.html
t3install     = https://docs.typo3.org/m/typo3/guide-installation/master/en-us/
# t3l10n        = https://docs.typo3.org/m/typo3/guide-frontendlocalization/master/en-us/
# t3start       = https://docs.typo3.org/m/typo3/tutorial-getting-started/master/en-us/
# t3sitepackage = https://docs.typo3.org/m/typo3/tutorial-sitepackage/master/en-us/
# t3tca         = https://docs.typo3.org/m/typo3/reference-tca/master/en-us/
# t3templating  = https://docs.typo3.org/m/typo3/tutorial-templating-with-fluid/master/en-us/
# t3ts45        = https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/master/en-us/
t3tsconfig    = https://docs.typo3.org/m/typo3/reference-tsconfig/master/en-us/
t3tsref       = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/

[extensions]
# This is required for embedding YouTube videos
any_name_youtube = sphinxcontrib.youtube

[alexander-nitsche]

(1) @gilbertsoft referred to https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual/blob/master/Documentation/Settings.cfg and added that version is not required anymore and release should be set via variable {extension.version}

(2) checking https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual/blob/master/Documentation/Settings.cfg also project and copyright should be set by variables and copyright does not contain the years but a "by {extension.extensionKey}"

(3) description is not used in the template https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual/blob/master/Documentation/Settings.cfg at all

(4) is the "Edit me on Github Button" section relevant for the TYPO3 system extensions: is GitHub contribution supported in any way?

[alexander-nitsche]

(4) is the "Edit me on Github Button" section relevant for the TYPO3 system extensions: is GitHub contribution supported in any way?

@linawolf : As far as I know it triggers a hook that makes a PR on forge @mbrodala : It's a fact. ^^ No idea how and where it's set up but this is what happens. A PR is created on GH as usual. A few moments later the change is pushed to Gerrit and the PR is closed with a comment linking to the Gerrit change. And yes, this even automatically creates the necessary Forge ticket. So whoever set this up is a genius. @linawolf : The only thing it doesn't work for is the Fluid Documentation which I think is a shame. At least we removed the Edit me on Github button so ppl stop trying. @susannemoog : A bit of background: for the core that is handled by intercept (intercept.typo3.com) - basically the Github PR event is used, intercept has it’s own core checkout, applies the pull request, opens a forge issue, pushes to gerrit and closes the PR via the API :) - the code is also publicly available on Github (https://github.com/TYPO3GmbH/site-intercept). @alexander-nitsche : ok, the GitHub part remains, but which parameters are required there? in the template Settings.cfg there are two params (github_branch, github_repository) and in some production Settings.cfg there are three (github_branch, github_repository, path_to_documentation_dir). @susannemoog : maybe @marble can shed some light on that - logically, if the repository is the main typo3/typo3 repo, path_to_documentation_dir would make sense, as we would need to indicate which extension is meant. @alexander-nitsche : ah ok, path_to_documentation_dir seems to be appended to the branch path of the repository configured by github_branch and github_repository and - if not set - would end up with https://github.com/typo3/typo3/edit/master/Documentation/* which does not exist ..

[alexander-nitsche]

still on the Settings.cfg: there are many styles in the TYPO3 Documentation and TYPO3 Core for [general] :

(5) project contains, among others, the following values: a) the project name, e.g. "Import / Export" b) the project key, e.g. "impexp" (edited)

(6) version and release contain, among others, the following values: -- Scope of TYPO3 Core -- a) latest (10-dev) (even in current master) b) master c) 10.4 (even in current master) -- Scope of TYPO3 Documentation -- a) master (8.7) b) 8.7.0 c) master (v9) d) 11.0 (development) e) latest f) master (10.x) g) master (9-dev) (edited)

(7) t3author contains, among others, the following values: -- Scope of TYPO3 Core -- a) TYPO3 CMS Core Team b) TYPO3 Core Team + Contributors, TYPO3 Documentation Team c) Kasper Skaarhoj -- Scope of TYPO3 Documentation -- a) Documentation Team b) TYPO3 Community c) TYPO3 Core Team, TYPO3 Documentation Team, TYPO3 Community d) TYPO3 community

(8) copyright contains, among others, the following values: -- Scope of TYPO3 Core -- a) 1997-2021 -- Scope of TYPO3 Documentation -- a) since 2011 by the TYPO3 Documentation Team b) Copyright since 2000 by the TYPO3 Documentation Team c) since 2012 by the authors and the TYPO3 Documentation Team d) Copyright since ever by the authors e) since 2000 by TYPO3 Association

(9) description has always the same style in TYPO3 Core

(10) and there are rumors that one can set dynamic variables – {extension.name} – {extension.version} – {extension.extensionKey} which get replaced automagically during rendering by related values from the ext_emconf.php. however, they remain quite static in my local rendering run ..

[alexander-nitsche]

My proposal for TYPO3 Core system extensions would be - based on the findings above:

[general]
project     = Admin Panel
version     = latest (11-dev) | 10.4 | 9.5
release     = latest (11-dev) | 10.4 | 9.5
t3author    = TYPO3 Core Team and TYPO3 Documentation Team
copyright   = since 1997 | 1998 | .. by the TYPO3 Core Team and the TYPO3 Documentation Team
description = This is the documentation of TYPO3's system extension 'adminpanel'.
              It displays a bar at the bottom of the screen on the frontend,
              from which you can access information per page.

what do you think?

[alexander-nitsche]

@susannemoog : copyright: since 1998 I'd say, as that is the one we officially agreed upon (2023 == 25 years :tada:)

[alexander-nitsche]

or we use the same version like the related ext_emconf.php to ease refactoring on each new TYPO3 release, for example

[general]
project     = Admin Panel
version     = latest (11.5.0) | 10.4.13 | 9.5.42
release     = latest (11.5) | 10.4 | 9.5
t3author    = TYPO3 Core Team and TYPO3 Documentation Team
copyright   = since 1997 | 1998 | .. by the TYPO3 Core Team and the TYPO3 Documentation Team
description = This is the documentation of TYPO3's system extension 'adminpanel'.
              It displays a bar at the bottom of the screen on the frontend,
              from which you can access information per page.

and whenever the version in ext_emconf.php gets raised, the same replacement routine can be applied to the Settings.cfg - as it gets forgotten currently sometimes, as it seems ..

[alexander-nitsche]

@susannemoog : I think when releasing darth is used to create/automate the changes (https://github.com/typo3/darth) maybe we can add a PR for that replacement logic there?

[sypets]

I hope it is ok, if I weigh in with the possibility that what I say is redundant because too much changed already. Just from past experience:

The one Settings.cfg that was used as "master" was the one in "Writing documenation".

I already spent hours and hours of unifying these type of things. Also .editorconfig which has already been changed again in only a few places.

The Index.rst is also not unified. We never really worked together on making decisions about these kind of things. So this, making one change after the next and not everyone knowing it and sticking to the conventions does not work.

I would strongly recommend to try to keep some general things in a common place and import it or automatically copy it if that is in any way possible instead of changing it in every single repo manually (I did do it that way but I regret this now).

And decide which repo is the master and used as example (usually "Writing documentation").

Otherwise document the conventions somewhere. That was also not always done in the past. The things were discussed somewhere on Slack and not written down.

Otherwise a lot of time is spent with those things and there are still a lot of repos (and branches) around.

Also, I think version and release are not both used. I would simplify the settings as much as possible and throw the ones out that are not used (which I already did in some places).

[mbrodala]

I'd also throw in my suggestion once more to merge all TYPO3 doc repositories into a single one. I still do not see the benefit of having multiple repositories. OTOH I see many benefits with a single repository:

• we could drop all cross-manual links which must be inserted and maintained manually
• We could re-use more content if appropriate
• We could define things centrally and once (like seen here)

The usual Symfony example would be https://github.com/symfony/symfony-docs which is the only repository that exists for https://symfony.com/doc/current/index.html.

[alexander-nitsche]

Hi Sybille,

this is issue is - as you require - about

(1) defining a standard, (2) processing it throughout the existing documentation and extensions (3) and persisting it in the documentation for later lookup.

For example see https://github.com/TYPO3-Documentation/T3DocTeam/issues/164 for a previous standard definition and procession. Nothing should get lost, absolutely agree.

[alexander-nitsche]

Hi Mathias, what about creating a new issue for your topic and discuss there? Greetings, Alex

[susannemoog]

@mbrodala I will propose to do exactly that next week :-D I even have it on my list already but wanted to check the implications first - Give me a few days and I'll take care of starting that topic - leaving this issue to its original purpose now ;)

[sypets]

thanks everyone - looks like you have got a grip on this - looking good and good luck! (moving to single repo will in fact make this much easier but I don't want to even begin to think about other implications like migration, broken links, 404 (red alert, panic!!!), what about core extension docs? etc.

But somehow I feel you will manage this as well ... :smile:

[marble]

Authorative example in the (future) Docker Rendering Container DRC

• I have used the above Settings.cfg as a starting point and added it as an example file in the repo that creates the Docker container. It is still in the develop branch.

• Please see https://github.com/t3docs/docker-render-documentation/blob/develop/ALL-for-build/Examples/Settings.cfg.01.minimal.cfg

• From a technical point of view I consider the specifications in that file as "authorative". And I've added comments for explanation. The [general] section is mandatory. Other sections are optional. And there are more possible sections that aren't mentioned yet in that example file.

• The advantage of having it in the container is, that it can easily be distributed. People just will have to say dockrun_t3rd export-ALL to find a copy on their disc.

Style is in your hands

• In no way the example is prescriptive about the style you choose for the Settings.cfg file. Keep, add or drop comments as you like and reformat as you like. Just provide a healthy syntax.

Beware…

• I haven't tested the example file, so there may be typos, that still need to be fixed.

[sypets]

my opinion: I like the explanations. Also keeping that in the docker repo seems like a good idea.

[marble]

FYI: After a long chat with @alexander-nitsche yesterday I felt inspired to find a solution to make some configuration values of Settings.cfg available in the text. Here is what I have got going so far (WIP):

[alexander-nitsche]

This issue is done with the publication of the new page File structure that contains the new standard regarding the Settings.cfg for official TYPO3 manuals and TYPO3 extension documentation.