[FEATURE] Add theme_info.json to distribution about sphinx_typo3_theme HOT 4 CLOSED

I am not sure if we really need a JSON file for the processing, as you can see in the open pull request I am done with automatic building and publishing of the theme to pip, that also means it can and should be installed that way. Then it´s really easy to fetch this information as we know its sphinx_typo3_theme and the version installed can get through pip.

pip3 list

pip3 show sphinx-typo3-theme

python3 -c "import sphinx_typo3_theme; print(sphinx_typo3_theme.__version_full__)"

python3 -c "import sphinx_typo3_theme; print(sphinx_typo3_theme.__version__)"

from sphinx_typo3_theme.

I need to be able to deduce the version from the rendered documentation. Because the toolchain does several steps of html postprocessing. For example, it's about adding 'rel="no-followow" to some links, some security checks and others. That's all done in the toolchain. Until now there had been a file like t3SphinxThemeRtd-3.6.0.txt in _static to identify the version. That wasn't the best idea.

The most important tweak of the rendered code is replacing the links to the static resources by absolute values relative to the server and removing the _static folder completely. Example: view-source:https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/

We have several thousands of manuals on the server and, at the moment, they are all sharing the same CSS and JS and _static. Which means, readers have to fetch those resources only once. And, we can deploy a (backwards compatible) theme change for all rendered stuff in one go by just changing the /t3SphinxThemeRtd/3.6/ location. We can update those _static files by means of the homepage repository. We have to be careful there: Stuff in the folder WebRootResources is deployed automatically and immediately to those absolute locations on the server. But only some of the files. lolli implemented it that way.

Before we roll out the new sphinx_typo3_theme we have to make sure we have provided the static files.

To have the container do the replacement you have to set the option "replace_static_in_html": 1. Consider:

{
  "Overrides_cfg": {
    "general": {
      "html_theme": "t3SphinxThemeRtd"
    },
    "html_theme_options": {
      "docstypo3org": "yes",
      "show_legalinfo": "yes"
    }
  },
  "tctconfig": {
    "disable_include_files_check": 0,
    "replace_static_in_html": 1
  }
}

The toolchain needs to know whether it may do the replacements and decide about where to point to.
After the theme update it doesn't find the indicator file and doesn't do the replacement.

With the old versioning scheme I could only change the patchlevel because all already rendered stuff is pointing to /t3SphinxThemeRtd/3.6. Including the many legacy manuals which we can't rerender easily as intercept doesn't know them. That's still most of the manuals.

Let me try define some new standards. We need a folder that's definitely available. Let's say /__theme(double underscore). Then we could have /__theme/sphinx_typo3_theme/1/_static in there. Where 1 is the MAJOR number Whenever we have a new theme version 1.x.x we would put a copy there. This will work as long as we don't introduce changes to the static files that ARE NOT compatible with the already rendered stuff (backwards compatibility). Until now with t3SphinxThemeRtd this had never happened.

But now, that we are introducing sphinx_theme_rtd we have that case. So we need another static place like __theme/sphinx_typo3_theme/<MAJOR> on the server.

You get the idea? @benjaminkott

from sphinx_typo3_theme.

@marble I have an idea can build it into the current open pr.

from sphinx_typo3_theme.

The theme will now generate a _static/theme.json file with the following contents.

{
    "name": "sphinx_typo3_theme",
    "version": "0.0.0",
    "version_full": "0.0.0",
    "options": {
        "docstypo3org": "yes",
        "github_branch": "master",
        "github_commit_hash": "",
        "github_repository": "TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument",
        "github_revision_msg": "",
        "github_sphinx_locale": "",
        "is_homepage": "",
        "logo": "img/typo3-logo.svg",
        "path_to_documentation_dir": "",
        "project_contact": "https://typo3.org/community/teams/documentation/#c9886",
        "project_discussions": "",
        "project_has_defaults_cfg": "",
        "project_has_overrides_cfg": "",
        "project_has_settings_cfg": "",
        "project_home": "https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument",
        "project_issues": "https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/issues",
        "project_repository": "https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument",
        "show_copyright": "yes",
        "show_last_updated": "yes",
        "show_sourcelink": "yes"
    }
}

from sphinx_typo3_theme.