Comments (4)
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.
Related Issues (20)
- Use white background for numbered sections like symfony HOT 1
- Text is white/gray HOT 9
- Reduce "visual clutter" by using different style for inline code (without background color)? HOT 3
- Clamp multiple paragraphs of directives like "versionadded" visually HOT 9
- Dark-on-dark syntax highlighting after upgrade HOT 5
- `t3-function-*` are not recognizable as links HOT 7
- Change request: 'view source' and 'Edit on GitHub' buttons could open in a new window HOT 9
- Copying code snippets will include line numbers HOT 11
- Indenting of code-blocks with captions is different from code blocks without captions HOT 2
- Re-enable gh-pages in CI.yml HOT 1
- Simplify '.. seealso::' appearance HOT 1
- Make .compact-list work everywhere HOT 1
- Update docs and gh-pages
- Make admonitions appear 'lighter' HOT 1
- Input value name "q" is in conflict with Sphinx code
- Change Html theme options and/or remove some parts of the sphinx_typo3_theme ? HOT 1
- Increase the size of contents in body of index HOT 3
- Include print.js for print to pdf to sphinx typo3 theme. HOT 2
- Using "rst-class:: bignums" has impact on subsequent lists HOT 3
- [Features] Content list and add a download 'view source' link or button
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from sphinx_typo3_theme.