Documentation links broken in 2.82 after recent documentation url changes for IO addons #74017

New Issue

Julien Duroure · 2020-02-19T21:46:29+01:00

Julien Duroure commented

2020-02-19 21:46:29 +01:00

System Information
Operating system: all
Graphics card: all

Blender Version
Broken: 2.82 official release
Worked: 2.81

Lots of documentation links for addon regarding import/export are broken, because of some recent change generating documentation.
For example https:*docs.blender.org/manual/en/dev/addons/import_export/io_scene_gltf2.html is changed to https:*docs.blender.org/manual/en/dev/addons/import_export/scene_gltf2.html, but all links in documentation addons are still with io_

I think the change must be reverted in documentation generation, to have some OK links in official 2.82
I checked the link few days before release on Feb. 2nd, and it was OK (cf 42d713b0a6)

It maybe linked to the fact that documentation seems to consider 2.82 as develop version

**System Information** Operating system: all Graphics card: all **Blender Version** Broken: 2.82 official release Worked: 2.81 Lots of documentation links for addon regarding import/export are broken, because of some recent change generating documentation. For example https:*docs.blender.org/manual/en/dev/addons/import_export/io_scene_gltf2.html is changed to https:*docs.blender.org/manual/en/dev/addons/import_export/scene_gltf2.html, but all links in documentation addons are still with io_ I think the change must be reverted in documentation generation, to have some OK links in official 2.82 I checked the link few days before release on Feb. 2nd, and it was OK (cf 42d713b0a6) It maybe linked to the fact that documentation seems to consider 2.82 as develop version

Julien Duroure commented

2020-02-19 21:46:29 +01:00

Added subscriber: @JulienDuroure

Aaron Carlisle commented

2020-02-19 22:16:26 +01:00

Added subscriber: @Blendify

Aaron Carlisle commented

2020-02-19 22:16:26 +01:00

Personally, I would rather not adjust the naming, leaving things as they are even if they are broken.
In the future, we need to not do this, which has to do with implementing blender/documentation#68432.

The 2.82 manual will be archived tomorrow so it is best IMHO to accept the issue and just move on.

Personally, I would rather not adjust the naming, leaving things as they are even if they are broken. In the future, we need to not do this, which has to do with implementing blender/documentation#68432. The 2.82 manual will be archived tomorrow so it is best IMHO to accept the issue and just move on.

Danny McGrath commented

2020-02-19 22:53:35 +01:00

Added subscriber: @dmcgrath

Danny McGrath commented

2020-02-19 22:53:35 +01:00

I supposed you could also use your .htaccess rights to create some redirects, and fix this yourself? I might need to enable something server side still for that, but in theory, it could allow you to manage your own breakage.

Just a thought!

I supposed you could also use your .htaccess rights to create some redirects, and fix this yourself? I might need to enable something server side still for that, but in theory, it could allow you to manage your own breakage. Just a thought!

Brecht Van Lommel commented

2020-02-19 22:57:35 +01:00

Added subscriber: @brecht

Brecht Van Lommel commented

2020-02-19 22:57:35 +01:00

@Blendify, I don't agree, this seems like a serious issue.

If the change is just the io_ being part of the page name, why is it hard to revert?

@Blendify, I don't agree, this seems like a serious issue. If the change is just the `io_` being part of the page name, why is it hard to revert?

Brecht Van Lommel commented

2020-02-19 22:58:30 +01:00

Changed status from 'Needs Triage' to: 'Confirmed'

Brecht Van Lommel commented

2020-02-19 22:58:30 +01:00

And we should definitely fix the add-ons docs links somehow including dev, it should contain the release number for official releases.

And we should definitely fix the add-ons docs links somehow including `dev`, it should contain the release number for official releases.

Danny McGrath commented

2020-02-19 23:07:29 +01:00

I took a look, and it appears that mod_rewrite stuff should be part of the FileInfo override that we already have in place. So you should be able to patch stuff up in the commits as well.

I took a look, and it appears that mod_rewrite stuff should be part of the `FileInfo` override that we already have in place. So you should be able to patch stuff up in the commits as well.

Aaron Carlisle self-assigned this 2020-02-19 23:51:50 +01:00

Aaron Carlisle commented

2020-02-19 23:51:50 +01:00

And we should definitely fix the add-ons docs links somehow including dev, it should contain the release number for official releases.

is there a way to add

    def manual_version(self, _context):
        if bpy.app.version_cycle in {"rc", "release"}:
            manual_version = "%d.%d" % bpy.app.version[:2]
        else:
            manual_version = "dev"
        return manual_version

to addon_utils.py? so we can

'wiki_url': "https://docs.blender.org/manual/en/' + manual_version + '/addons/import_export/io_scene_gltf2.html",

If not we can manually bump the version with the release but I would rather automate this.

For the moment I am working on a redirect that we can enable for the release

> And we should definitely fix the add-ons docs links somehow including dev, it should contain the release number for official releases. is there a way to add ``` def manual_version(self, _context): if bpy.app.version_cycle in {"rc", "release"}: manual_version = "%d.%d" % bpy.app.version[:2] else: manual_version = "dev" return manual_version ``` to `addon_utils.py`? so we can ``` 'wiki_url': "https://docs.blender.org/manual/en/' + manual_version + '/addons/import_export/io_scene_gltf2.html", ``` If not we can manually bump the version with the release but I would rather automate this. ------ For the moment I am working on a redirect that we can enable for the release

Danny McGrath commented

2020-02-20 00:21:49 +01:00

In #74017#876496, @Blendify wrote:

And we should definitely fix the add-ons docs links somehow including dev, it should contain the release number for official releases.

is there a way to add
    def manual_version(self, _context):
        if bpy.app.version_cycle in {"rc", "release"}:
            manual_version = "%d.%d" % bpy.app.version[:2]
        else:
            manual_version = "dev"
        return manual_version
to addon_utils.py? so we can
'wiki_url': "https://docs.blender.org/manual/en/' + manual_version + '/addons/import_export/io_scene_gltf2.html",
If not we can manually bump the version with the release but I would rather automate this.

For the moment I am working on a redirect that we can enable for the release

Well, there is rewrite maps which can do a lookup (re: the io_ redirects), but I can't seem to find if anything on if it can dynamically handle just redirects using code (I swore it could, but can't find info), short of just making it a dynamic site with some python code that would need to have an admin reload the server every time you update it. In all honesty, it's hard to beat the performance and simplicity of just using standard file system mechanisms: symlinks, fixed paths, static html, etc.

TBH, I'm not sure that you would want to go that route, regardless. As soon as Python gets involved, I think mod_python in Apache may still be stuck at 2.7? I forget the details, but using mod_python was problematic for us in the past because you can only have one version of it, and we had py2 and py3 code that needed to run, so the only real alternative is CGI type setups, which afaik, don't work with .htaccess rules that you already use for 404's.

Personally, I like the KISS principle for such things. But, feel free to test stuff in a local Apache setup and pass along some config for what you want, and I can possibly accommodate just about anything that works, and is needed/approved.

> In #74017#876496, @Blendify wrote: >> And we should definitely fix the add-ons docs links somehow including dev, it should contain the release number for official releases. > > is there a way to add > > ``` > def manual_version(self, _context): > if bpy.app.version_cycle in {"rc", "release"}: > manual_version = "%d.%d" % bpy.app.version[:2] > else: > manual_version = "dev" > return manual_version > ``` > > to `addon_utils.py`? so we can > > ``` > 'wiki_url': "https://docs.blender.org/manual/en/' + manual_version + '/addons/import_export/io_scene_gltf2.html", > ``` > > If not we can manually bump the version with the release but I would rather automate this. > > ------ > > > For the moment I am working on a redirect that we can enable for the release Well, there is [rewrite maps ](https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html#rewritemap) which can do a lookup (re: the io_ redirects), but I can't seem to find if anything on if it can dynamically handle just redirects using code (I swore it could, but can't find info), short of just making it a dynamic site with some python code that would need to have an admin reload the server every time you update it. In all honesty, it's hard to beat the performance and simplicity of just using standard file system mechanisms: symlinks, fixed paths, static html, etc. TBH, I'm not sure that you would want to go that route, regardless. As soon as Python gets involved, I think mod_python in Apache may still be stuck at 2.7? I forget the details, but using mod_python was problematic for us in the past because you can only have one version of it, and we had py2 and py3 code that needed to run, so the only real alternative is CGI type setups, which afaik, don't work with .htaccess rules that you already use for 404's. Personally, I like the KISS principle for such things. But, feel free to test stuff in a local Apache setup and pass along some config for what you want, and I can possibly accommodate just about anything that works, and is needed/approved.

Aaron Carlisle commented

2020-02-20 00:34:37 +01:00

To clarify on Trouble's comment, I meant to automatically adjust the version number from the addon side instead of the server-side.

Brecht Van Lommel commented

2020-02-20 01:42:10 +01:00

@Blendify, maybe something like this (untested):

diff --git a/release/scripts/modules/addon_utils.py b/release/scripts/modules/addon_utils.py
index b58c683dc24..aebb465a037 100644
--- a/release/scripts/modules/addon_utils.py
+++ b/release/scripts/modules/addon_utils.py
@@ -506,6 +506,7 @@ def module_bl_info(mod, info_basis=None):
             "location": "",
             "description": "",
             "wiki_url": "",
+            "manual_reference": "",
             "support": 'COMMUNITY',
             "category": "",
             "warning": "",
@@ -527,5 +528,12 @@ def module_bl_info(mod, info_basis=None):
     if not addon_info["name"]:
         addon_info["name"] = mod.__name__

+    if not addon_info["wiki_url"] and addon_info["manual_reference"]:
+        if _bpy.app.version_cycle in {"rc", "release"}:
+            manual_version = "%d.%d" % _bpy.app.version[:2]
+        else:
+            manual_version = "dev"
+      addon_info["wiki_url"] = "https://docs.blender.org/manual/en/" + manual_version + "/" + addon_info["manual_reference"]
+
     addon_info["_init"] = None
     return addon_info

@Blendify, maybe something like this (untested): ``` diff --git a/release/scripts/modules/addon_utils.py b/release/scripts/modules/addon_utils.py index b58c683dc24..aebb465a037 100644 --- a/release/scripts/modules/addon_utils.py +++ b/release/scripts/modules/addon_utils.py @@ -506,6 +506,7 @@ def module_bl_info(mod, info_basis=None): "location": "", "description": "", "wiki_url": "", + "manual_reference": "", "support": 'COMMUNITY', "category": "", "warning": "", @@ -527,5 +528,12 @@ def module_bl_info(mod, info_basis=None): if not addon_info["name"]: addon_info["name"] = mod.__name__ + if not addon_info["wiki_url"] and addon_info["manual_reference"]: + if _bpy.app.version_cycle in {"rc", "release"}: + manual_version = "%d.%d" % _bpy.app.version[:2] + else: + manual_version = "dev" + addon_info["wiki_url"] = "https://docs.blender.org/manual/en/" + manual_version + "/" + addon_info["manual_reference"] + addon_info["_init"] = None return addon_info ```

Aaron Carlisle commented

2020-02-20 05:08:13 +01:00

I have added a redirect so the initial report is fixed. In the future, now that we know can do this, hopefully, create an automated (maybe semi-manual) method to write redirects.

The patch you came up with is something I also thought about so for 2.83 we can do that.

I have added a redirect so the initial report is fixed. In the future, now that we know can do this, hopefully, create an automated (maybe semi-manual) method to write redirects. The patch you came up with is something I also thought about so for 2.83 we can do that.

Aaron Carlisle commented

2020-02-20 05:09:24 +01:00

Leaving as a todo to address the URL for 2.83

Brendon Murphy commented

2020-02-20 08:31:04 +01:00

Added subscribers: @ideasman42, @BrendonMurphy

Brendon Murphy commented

2020-02-20 08:31:04 +01:00

hi, I think this is not a good solution unless it's temporary. Leading up to 2.82 bcon2, I made sure all addons linked to their correct manual pages. Every included addon should have a permanent page on the Manual.
If this only affects i/o addons then we can simply change the bl_info wiki_url to point to the correct manual page leading up to 2.83.
Adding a duplicate field to all addons: wiki_url and the proposed manual_url are the same thing, an internally used name to point addons to their documentation. @ideasman42 what is your opinion here?
@Blendify
If this change has broken all 2.82 i/o manual links, it will need to be redirected by the manual until 2.83.
I'm happy to help fix the i/o addons current links in 2.83 master, linking them to the new manual page.

hi, I think this is not a good solution unless it's temporary. Leading up to 2.82 bcon2, I made sure all addons linked to their correct manual pages. Every included addon should have a permanent page on the Manual. If this only affects i/o addons then we can simply change the bl_info wiki_url to point to the correct manual page leading up to 2.83. Adding a duplicate field to all addons: wiki_url and the proposed manual_url are the same thing, an internally used name to point addons to their documentation. @ideasman42 what is your opinion here? @Blendify If this change has broken all 2.82 i/o manual links, it will need to be redirected by the manual until 2.83. I'm happy to help fix the i/o addons current links in 2.83 master, linking them to the new manual page.

Brecht Van Lommel commented

2020-02-20 13:08:12 +01:00

The idea with my patch would be to have either a manual_reference or a wiki_url for an add-on info, never both. When the add-on is loaded, the URL will then be expanded to include the version.

Instead of adding another field, we could keeping using wiki_url but have something like this:

wiki_url = "{BLENDER_MANUAL_URL}/addons/import_export/scene_gltf2.html"

Which then gets expanded to include the proper version (and language?).

The idea with my patch would be to have either a `manual_reference` or a `wiki_url` for an add-on info, never both. When the add-on is loaded, the URL will then be expanded to include the version. Instead of adding another field, we could keeping using `wiki_url` but have something like this: ``` wiki_url = "{BLENDER_MANUAL_URL}/addons/import_export/scene_gltf2.html" ``` Which then gets expanded to include the proper version (and language?).

Sybren A. Stüvel commented

2020-02-20 13:55:24 +01:00

Added subscriber: @dr.sybren

Sybren A. Stüvel commented

2020-02-20 13:55:24 +01:00

In #74017#876830, @brecht wrote:
The idea with my patch would be to have either a manual_reference or a wiki_url for an add-on info, never both.
[…]
Instead of adding another field, we could keeping using wiki_url

In that case I would vote for changing the key to documentation_url. It can point to the wiki or the manual, or anywhere else. Naming something 'wiki' but allowing it to have non-wiki values, that looks confusing to me.

wiki_url = "{BLENDER_MANUAL_URL}/addons/import_export/scene_gltf2.html"
Which then gets expanded to include the proper version (and language?).

I like the idea, but this is very close to Python's f"" notation. Maybe "$BLENDER_MANUAL_URL/addons/import_export/scene_gltf2.html"? Or ${BLENDER_MANUAL_URL} if you want it to be more 'enclosed'.

> In #74017#876830, @brecht wrote: > The idea with my patch would be to have either a `manual_reference` or a `wiki_url` for an add-on info, never both. > […] > Instead of adding another field, we could keeping using `wiki_url` In that case I would vote for changing the key to `documentation_url`. It can point to the wiki or the manual, or anywhere else. Naming something 'wiki' but allowing it to have non-wiki values, that looks confusing to me. > ``` > wiki_url = "{BLENDER_MANUAL_URL}/addons/import_export/scene_gltf2.html" > ``` > Which then gets expanded to include the proper version (and language?). I like the idea, but this is very close to Python's `f""` notation. Maybe `"$BLENDER_MANUAL_URL/addons/import_export/scene_gltf2.html"`? Or `${BLENDER_MANUAL_URL}` if you want it to be more 'enclosed'.

Brecht Van Lommel commented

2020-02-20 14:02:23 +01:00

That's all fine with me, the precise naming and syntax I'll leave up to Python and Add-on project maintainers. If we want to rename wiki_url, it can be done in a way that's backwards compatible.

Mainly I wanted to suggest that constructing the URL should be done by Blender, so that we can more easily change it if we need to later. For example to support taking into account the language, or using downloaded docs rather than a website.

That's all fine with me, the precise naming and syntax I'll leave up to Python and Add-on project maintainers. If we want to rename `wiki_url`, it can be done in a way that's backwards compatible. Mainly I wanted to suggest that constructing the URL should be done by Blender, so that we can more easily change it if we need to later. For example to support taking into account the language, or using downloaded docs rather than a website.

Tobias Heinke commented

2020-02-20 19:54:46 +01:00

Added subscriber: @Tobias

Tobias Heinke commented

2020-02-20 19:54:46 +01:00

This comment was removed by @Tobias

*This comment was removed by @Tobias*

Aaron Carlisle commented

2020-02-20 20:26:14 +01:00

@Tobias can you better explain that, you have a double negative and I am not exactly sure what part of this task you are responding to.

Tobias Heinke commented

2020-02-20 23:13:36 +01:00

never mind, I overlooked that you have edited the script.

Aaron Carlisle commented

2020-03-05 05:37:29 +01:00

Changed status from 'Confirmed' to: 'Resolved'

Aaron Carlisle closed this issue

2020-03-05 05:37:29 +01:00

Aaron Carlisle commented

2020-03-05 05:37:29 +01:00

In #74017#876470, @brecht wrote:
And we should definitely fix the add-ons docs links somehow including dev, it should contain the release number for official releases.

This has been updated in blender/blender@a0ea0153c2 I will update all the addon URLs.

> In #74017#876470, @brecht wrote: > And we should definitely fix the add-ons docs links somehow including `dev`, it should contain the release number for official releases. This has been updated in blender/blender@a0ea0153c2 I will update all the addon URLs.

Julien Duroure commented

2020-03-05 06:19:47 +01:00

@Blendify Is that something that will be added in 2.82a ?

Aaron Carlisle commented

2020-03-05 07:23:49 +01:00

No, it is not a big deal. Will be a part of 2.83

Brecht Van Lommel commented

2020-03-05 08:35:32 +01:00

My understanding is that the links in 2.82 work now due to redirects, but they will point to the latest version of the docs rather tham the 2.82 version specifically.

If so, I agree that's not something critical to fix for 2.82a.

My understanding is that the links in 2.82 work now due to redirects, but they will point to the latest version of the docs rather tham the 2.82 version specifically. If so, I agree that's not something critical to fix for 2.82a.

Julien Duroure commented

2020-03-05 08:51:50 +01:00

Sorry, I thought the redirection was not effective, but seems it was my browser cache that was not updated
So, I agree this is not critical too, redirection will do the job until 2.83

Sorry, I thought the redirection was not effective, but seems it was my browser cache that was not updated So, I agree this is not critical too, redirection will do the job until 2.83

Sign in to join this conversation.