Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Link to correct version of other manual with intersphinx linking #81

Closed
sypets opened this issue May 16, 2019 · 5 comments
Closed

Link to correct version of other manual with intersphinx linking #81

sypets opened this issue May 16, 2019 · 5 comments

Comments

@sypets
Copy link
Contributor

@sypets sypets commented May 16, 2019

This issue was raised by @rowild in Slack:

and @DanielSiepmann added some ideas. Thank you!

The intersphinx linking (as specified in Settings.cfg) currently always go to "latest". This is also the case for older branches.

Should we change the links for the other branches in Settings.cfg to link to matching versions (or best match), e.g. branch 8.7 in "TYPO3 Explained" should link to branch 8.7 in TCA Reference?

There are several related issues (which have also been mentioned in Slack ):

  • Not all repositories have an up-to-date "latest", sometimes "latest" is actually "7.6" or something else
  • Not having the version selector easily visible is a real problem, I think. I don't think everyone is aware of the fact, that there are other versions available. See also Improve the version switcher - "unhide" it
  • Branching out and keeping branches up-to-date.
@rowild

This comment has been minimized.

Copy link

@rowild rowild commented May 16, 2019

Thank you very much for opening this ticket, @sypets ! The complexity of the documentation is indeed something that requires a team that is fully dedicated to it.
As for the visibility of the selector: the non-visibility is especially true for mobile phones...

@DanielSiepmann

This comment has been minimized.

Copy link
Member

@DanielSiepmann DanielSiepmann commented May 17, 2019

I guess this might work:

All repositories must contain the latest branch, following the structure to be the "default" if no version is added to the URL. We do not change anything within latest branch. The current behaviour is kept.

For each older branch, we adjust Settings.cfg to contain the version number within intersphinx URLs.
Therefore each repository must provide a branch / version for each LTS beforehand.

Once a new LTS is released, e.g. upcoming V10.x, we create a new Branch for older LTS (V9.5) within each repository and render those. Afterwards we can adjust the Settings.cfg of each repository to adjust the intersphinx URLs to point to 9.5 of each referenced manual.

This way each version should only contain links to the same version when cross referencing.

It's important to always use Sphinx :ref: text role to make use of intersphinx, and never to add raw external URLs, in order to make this work.

We should also coordinate this with Core Team and TYPO3 Inc. As CoreTeam is managing Systemenxtension Manuals and Changelog.
The TYPO3 Inc. is working on new URL structure and Rendering / Deployment of Manuals. Maybe they have also some input to that topic.

@sypets

This comment has been minimized.

Copy link
Contributor Author

@sypets sypets commented May 17, 2019

@DanielSiepmann It seems we should use "master" instead of "latest" (see #39), but this does not affect the general principles. But since main branch is currently not being used consistent, I thought I might mention it to see if this is something which must be coordinated with GmbH

I don't think we will always get an exact match.Right now, some repos have "latest" not being 9.5. For "Sitepackage Tutorial", it is 8.7. For "Fronend Localization Guide", it is 7.6. So sometimes it will link to same version and sometimes not (if same version is not available).

That is a little unfortunate, but I think we have to be pragmatic. In most of the cases, the behaviour will be improved.

And improvements in usability with version selector might help here as well.

So, it might look like this?

Settings.cfg of 7.6 branch of "TYPO3 Explained":

# these manuals only have one version
h2document    = https://docs.typo3.org/typo3cms/HowToDocument/
t3contribute  = https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/
t3extbasebook = https://docs.typo3.org/typo3cms/ExtbaseFluidBook/


t3install     = https://docs.typo3.org/typo3cms/InstallationGuide/7.6/
t3start       = https://docs.typo3.org/typo3cms/GettingStartedTutorial/7.6
t3tca         = https://docs.typo3.org/typo3cms/TCAReference/7.6
...
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-CoreApi that referenced this issue Dec 29, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-CoreApi that referenced this issue Dec 29, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-CoreApi that referenced this issue Dec 29, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-CoreApi that referenced this issue Dec 29, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Guide-FrontendLocalization that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Guide-FrontendLocalization that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Guide-FrontendLocalization that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Guide-Installation that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Guide-Installation that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Guide-Installation that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Guide-Installation that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TCA that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TCA that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TCA that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TCA that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TSconfig that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TSconfig that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TSconfig that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TSconfig that referenced this issue Dec 30, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Tutorial-Editors that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Tutorial-GettingStarted that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Tutorial-GettingStarted that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Tutorial-GettingStarted that referenced this issue Dec 31, 2019
sypets added a commit to sypets/TYPO3CMS-Tutorial-Typoscript45Minutes that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TyposcriptSyntax that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TyposcriptSyntax that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-TyposcriptSyntax that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-InsideTypo3 that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-InsideTypo3 that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-CodingGuidelines that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-Typo3Services that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-Typo3Services that referenced this issue Dec 31, 2019
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Reference-FileAbstractionLayer that referenced this issue Jan 1, 2020
sypets added a commit to TYPO3-Documentation/TYPO3CMS-Guide-Security that referenced this issue Jan 1, 2020
@sypets

This comment has been minimized.

Copy link
Contributor Author

@sypets sypets commented Jan 3, 2020

I changed the Settings.cfg to link to same version in all official manuals.

@sypets

This comment has been minimized.

Copy link
Contributor Author

@sypets sypets commented Jan 3, 2020

I created a patch to make this change in the core as well: https://review.typo3.org/c/Packages/TYPO3.CMS/+/62814

sypets added a commit to sypets/DocsTypo3Org-Homepage that referenced this issue Jan 3, 2020
When linking from one manual to another, we previously always linked to
the latest (master) version of the manual.

We now changed the procedure, so that links across manuals link
to the documentation for the same TYPO3 version.

Related: TYPO3-Documentation/T3DocTeam#81
@sypets sypets closed this Jan 3, 2020
sypets added a commit to sypets/DocsTypo3Org-Homepage that referenced this issue Jan 3, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.