Docs: Split Addons to its own project #81264

New Issue

Aaron Carlisle · 2020-09-28T20:20:10+02:00

Aaron Carlisle commented

2020-09-28 20:20:10 +02:00

Rationale

Addon docs are currently included as part of the main manual however it would be better if they were their own project for a couple reasons.

It would be helpful to have them as separate projects to prioritize the manual over add-ons mainly for translations but it would also simplify the main manual project.
Currently, the translation cover both the manual and the addons however as things are currently we dont have the community resources to translate both.
Splitting the projects would allow us to disable the translations for one and enable them for the other.
This change is especially important in the future if we increase the amount of add-ons and when the addons manual is updated with content.
(Much of the addon docs are incomplete ATM).

Implementation

Create a new sphinx project
Addon docs will now be hosted at docs.blender.org/addons/official/ (community and testing can be added in the future; these would be added to this new project).

Questions

Should we create a new repository or create a directory under trunk of rBM?

Tasks

Move to new project
Update internal links
Get new project building on server
Update https://docs.blender.org/
Create Redirects
Update Addons URLs

Rationale **** Addon docs are currently included as part of the main manual however it would be better if they were their own project for a couple reasons. It would be helpful to have them as separate projects to prioritize the manual over add-ons mainly for translations but it would also simplify the main manual project. Currently, the translation cover both the manual and the addons however as things are currently we dont have the community resources to translate both. Splitting the projects would allow us to disable the translations for one and enable them for the other. This change is especially important in the future if we increase the amount of add-ons and when the addons manual is updated with content. (Much of the addon docs are incomplete ATM). Implementation **** - Create a new sphinx project - Addon docs will now be hosted at `docs.blender.org/addons/official/` (community and testing can be added in the future; these would be added to this new project). Questions **** - Should we create a new repository or create a directory under trunk of rBM? Tasks **** - [ ] Move to new project - [ ] Update internal links - [ ] Get new project building on server - [ ] Update https://docs.blender.org/ - [ ] Create Redirects - [ ] Update Addons URLs

Aaron Carlisle commented

2020-09-28 20:20:10 +02:00

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

Aaron Carlisle commented

2020-09-28 20:20:10 +02:00

Added subscriber: @Blendify

Campbell Barton commented

2020-09-29 02:32:13 +02:00

Added subscriber: @ideasman42

Campbell Barton commented

2020-09-29 02:32:13 +02:00

While I'm interested in feedback from others... as far as I can see this has mostly down-sides for us.

We have to manage building 2x documentation repos.
We need to sync changes between the repos configuration, css tweaks & theme.
We have to store versioned zipfiles for each manual for release, anyone who wants to download the manual needs to remember to get both.
We can't as easily reference add-ons to/from the manual.
Any checks or automated edits need to be performed in 2x repositories.
Utilities added to the manual repository wont be accessible in the other repository unless we copy them there.
Add-ons that are enabled by default and might even be considered core functionality aren't part of the manual, and wont be translated, even if we want them to be.

To sum it up, it's adding a reasonable amount of maintenance overhead for a fairly small part of the manual.

If we don't have the resources to translate add-ons. I don't see any problems with not translating them. We could make this more official (exclude them from the translation completion reports for example, & not add PO files for them).

Further, there are loose plans to move to having most add-ons maintained in a distributed way (using a package manager), so I don't think it's worth spending a lot of time on this.

While I'm interested in feedback from others... as far as I can see this has mostly down-sides for us. - We have to manage building 2x documentation repos. - We need to sync changes between the repos configuration, css tweaks & theme. - We have to store versioned zipfiles for each manual for release, anyone who wants to download the manual needs to remember to get both. - We can't as easily reference add-ons to/from the manual. - Any checks or automated edits need to be performed in 2x repositories. - Utilities added to the manual repository wont be accessible in the other repository unless we copy them there. - Add-ons that are enabled by default and might even be considered core functionality aren't part of the manual, and wont be translated, even if we want them to be. To sum it up, it's adding a reasonable amount of maintenance overhead for a fairly small part of the manual. If we don't have the resources to translate add-ons. I don't see any problems with not translating them. We could make this more official (exclude them from the translation completion reports for example, & not add PO files for them). Further, there are loose plans to move to having most add-ons maintained in a distributed way (using a package manager), so I don't think it's worth spending a lot of time on this.

Aaron Carlisle commented

2020-10-01 03:31:34 +02:00

Changed status from 'Confirmed' to: 'Archived'

Aaron Carlisle closed this issue

2020-10-01 03:31:34 +02:00

Aaron Carlisle self-assigned this 2020-10-01 03:31:34 +02:00

Aaron Carlisle commented

2020-10-01 03:31:34 +02:00

Talked on Campbell a little about this in chat. We decided to if its really need to disable the generation of the translation files.
Moving addons to there own documentation project will be re-evaluated in the future when the addon distribution process gets revamped.

Some comments for future reference:

We have to manage building 2x documentation repos.

Wouldnt be that much work scripts can be more generalized and re-used

We need to sync changes between the repos configuration, css tweaks & theme

This is already and issue with the manual and the API docs, solution would be to merge our changes upstream.

We have to store versioned zipfiles for each manual for release, anyone who wants to download the manual needs to remember to get both.

I think this is a feature, someone who wants to download the manual might not need all the information about each addon.

We can't as easily reference add-ons to/from the manual.

We can with intersphinx extension which we already use to link to/from the manual and API docs

Any checks or automated edits need to be performed in 2x repositories.

These are mostly automated and do not require much maintenance overhead.

Utilities added to the manual repository wont be accessible in the other repository unless we copy them there.

Not a big deal these can be moved to a new repository

Add-ons that are enabled by default and might even be considered core functionality aren't part of the manual, and wont be translated, even if we want them to be.

These should probably be documented in manual still. (Can be duplicated to its own addon doc also).

Talked on Campbell a little about this in chat. We decided to if its really need to disable the generation of the translation files. Moving addons to there own documentation project will be re-evaluated in the future when the addon distribution process gets revamped. Some comments for future reference: > We have to manage building 2x documentation repos. Wouldnt be that much work scripts can be more generalized and re-used > We need to sync changes between the repos configuration, css tweaks & theme This is already and issue with the manual and the API docs, solution would be to merge our changes upstream. > We have to store versioned zipfiles for each manual for release, anyone who wants to download the manual needs to remember to get both. I think this is a feature, someone who wants to download the manual might not need all the information about each addon. > We can't as easily reference add-ons to/from the manual. We can with intersphinx extension which we already use to link to/from the manual and API docs > Any checks or automated edits need to be performed in 2x repositories. These are mostly automated and do not require much maintenance overhead. > Utilities added to the manual repository wont be accessible in the other repository unless we copy them there. Not a big deal these can be moved to a new repository > Add-ons that are enabled by default and might even be considered core functionality aren't part of the manual, and wont be translated, even if we want them to be. These should probably be documented in manual still. (Can be duplicated to its own addon doc also).

Campbell Barton commented

2020-10-05 08:10:28 +02:00

@Blendify sure there are solutions to issues I mention but they do complicate our documentation, you can argue it's not by much - or that it's worthwhile. But it moves away from a single manual you can build with one command - towards something that becomes more involved to manage IMHO.

If someone wants to edit docs for a an add-on and link to it - all of a sudden they need to know about intersphinx, with multiple repositories checked out.
If we want to share scripts between repositories, we have to introduce svn-externs.
If someone forgets to copy-paste changes between repositories someone needs to make sure that happens (from time to time).

Keep in mind the current hoops to jump through to make changes are already reasonably high for some contributors, I'd prefer if we keep things simple where possible.

@Blendify sure there are solutions to issues I mention but they _do_ complicate our documentation, you can argue it's not by much - or that it's worthwhile. But it moves away from a single manual you can build with one command - towards something that becomes more involved to manage IMHO. - If someone wants to edit docs for a an add-on and link to it - all of a sudden they need to know about intersphinx, with multiple repositories checked out. - If we want to share scripts between repositories, we have to introduce svn-externs. - If someone forgets to copy-paste changes between repositories someone needs to make sure that happens (from time to time). Keep in mind the current hoops to jump through to make changes are already reasonably high for some contributors, I'd prefer if we keep things simple where possible.

Sign in to join this conversation.