Proposal: Addon documentation for 2.8 #54097

New Issue

Aaron Carlisle · 2018-02-18T18:44:58+01:00

Aaron Carlisle commented

2018-02-18 18:44:58 +01:00

NOTE: This is still WIP and would like to hear some feedback from other core devs along with some addon devs.

Current Issues

Addon docs are removed from source

One of the current issues is that the source files for add-ons and the documents are handled in two different locations. This makes the documentation hard to keep updated with the

Broken wiki

The current wiki is broken and dead which has left the quality of addon documentation behind.

Proposal: Keep docs with code

A solution that has driven the success of documentation is keeping the documentation with the code. The solution has proved to work for Read the Docs and many other opensource projects.

See also: This idea of keeping docs and code together was illustrated by this presentation describing the philosophy behind RTD: https://www.youtube.com/watch?v=U6ueKExLzSY

Move to Sphinx

The current wiki documentation for add-ons is very sub-par with a lot of outdated/missing content. We want docs for our add-ons but make it very hard to edit the wiki.

So the proposal is similar to what we did with the manual. We will have one sphinx project where each addon has an index.rst the file where they can document their add-on how they please.

So the structure would look like this:

rBA
   - index.rst (overall index file)
   - conf.py
   - /add_curve_sapling
      - index.rst
      - other_rstfile.rst

Then the same can be done for contrib addons as well.

Require changes to docs with changes to addons

I think this is an idea that we want to aim for and can be much easier with having docs in the source.

Where would the docs live?

Add-ons: docs.blender.org/addons/<blender_version>/<addon_name>
Add-ons contrib: docs.blender.org/addons_contrib/<blender_version>/<addon_name>

Issues

I want images in my docs

Images do not work well with GIT, however, I think a solution to this is using git-lfs .

I don't want to build every doc to just view edits to my addon

We can write a script similar to the one included with the manual: https://developer.blender.org/diffusion/BM/browse/trunk/blender_docs/manual/quicky_index_gen.py

Single file addons

We probably won't be able to support this we this structure so all add-ons will have to be in a directory. Unless we can extract documentation from these py-files.

> **NOTE:** This is still WIP and would like to hear some feedback from other core devs along with some addon devs. Current Issues **** Addon docs are removed from source ------ One of the current issues is that the source files for add-ons and the documents are handled in two different locations. This makes the documentation hard to keep updated with the Broken wiki ----------- The current wiki is broken and dead which has left the quality of addon documentation behind. Proposal: Keep docs with code **** A solution that has driven the success of documentation is keeping the documentation with the code. The solution has proved to work for Read the Docs and many other opensource projects. > **See also:** This idea of keeping docs and code together was illustrated by this presentation describing the philosophy behind RTD: https://www.youtube.com/watch?v=U6ueKExLzSY Move to Sphinx --------- The current wiki documentation for add-ons is very sub-par with a lot of outdated/missing content. We want docs for our add-ons but make it very hard to edit the wiki. So the proposal is similar to what we did with the manual. We will have one sphinx project where each addon has an `index.rst` the file where they can document their add-on how they please. So the structure would look like this: ``` rBA - index.rst (overall index file) - conf.py - /add_curve_sapling - index.rst - other_rstfile.rst ``` Then the same can be done for contrib addons as well. Require changes to docs with changes to addons --------------------------------------------------- I think this is an idea that we want to aim for and can be much easier with having docs in the source. Where would the docs live? ---------------------------- Add-ons: docs.blender.org/addons/<blender_version>/<addon_name> Add-ons contrib: docs.blender.org/addons_contrib/<blender_version>/<addon_name> Issues **** I want images in my docs ----------------------------- Images do not work well with GIT, however, I think a solution to this is using [git-lfs ](https://git-lfs.github.com). I don't want to build every doc to just view edits to my addon ------------------------------ We can write a script similar to the one included with the manual: https://developer.blender.org/diffusion/BM/browse/trunk/blender_docs/manual/quicky_index_gen.py Single file addons --------- We probably won't be able to support this we this structure so all add-ons will have to be in a directory. Unless we can extract documentation from these py-files.

Aaron Carlisle commented

2018-02-18 18:44:58 +01:00

Added subscribers: @Blendify, @BrendonMurphy, @VukGardasevic, @ideasman42, @Ton

Aaron Carlisle commented

2018-02-18 18:48:27 +01:00

Added subscribers: @mont29, @Sergey

Aaron Carlisle commented

2018-02-18 23:49:30 +01:00

I can provide a live example if needed.

Campbell Barton commented

2018-02-19 00:16:05 +01:00

While I like the idea of keeping the addon and it's docs in the same repo.
git+lfs is quite advanced / tricky to use.
So I'm not sure about depending on this.

A wiki isn't inherently broken/dysfunctional.
The wiki works fine for developer docs for eg, so am inclined to leave addon docs there.

Perhaps move to a new wiki as has been discussed before.

An alternative could be to document add-ons in the reference-manual - they're distributed with Blender so this isn't a mis-use,
although we would want to ask active addon developers what they think of this.

My impression is they would prefer to keep something like a wiki where they have their own page they can edit.

Bigger picture - for 2.8x release I'd like to re-evaluate how we handle add-ons, it seems developers are moving away from wanting to develop in our git repo and instead use github and/or blendermarket. We might look into reducing the number of add-ons we distribute with Blender and instead look into having a package manager for 3rd party add-ons. For this reason I would hold off making big changes to how we document add-ons at this moment.

While I like the idea of keeping the addon and it's docs in the same repo. git+lfs is quite advanced / tricky to use. So I'm not sure about depending on this. A wiki isn't inherently broken/dysfunctional. The wiki works fine for developer docs for eg, so am inclined to leave addon docs there. Perhaps move to a new wiki as has been discussed before. ---- An alternative could be to document add-ons in the reference-manual - they're distributed with Blender so this isn't a mis-use, although we would want to ask active addon developers what they think of this. My impression is they would prefer to keep something like a wiki where they have their own page they can edit. ---- **Bigger picture** - for 2.8x release I'd like to re-evaluate how we handle add-ons, it seems developers are moving away from wanting to develop in our git repo and instead use github and/or blendermarket. We might look into reducing the number of add-ons we distribute with Blender and instead look into having a package manager for 3rd party add-ons. For this reason I would hold off making big changes to how we document add-ons at this moment.

stephen leger commented

2018-02-19 02:53:20 +01:00

Added subscriber: @StephenLeger

stephen leger commented

2018-02-19 02:53:20 +01:00

Hi,
+1 for .rst documentation.

But keep in mind that it is one more step added into the addon dev work.
In the other hand, allowing external documentation is an alternative as anyone is able to make it the easyest way - and won't require any action (publish rights into wiki and so on).

In order to make devs live easyer, you (we) must provide .rst templates as quick starting point, a clear step by step tutorial on how to setup python sphinx package - or creating some "dev toolkit" - so even without rst knowledge anyone is able to kikstart a doc project.

Github provide by far easyest ways to contribute with dedicated apps, hiding git logic behind nice gui or even right through web interface, and also provide ways to publish documentation using gh-pages branch (this also allow users to contribute into doc).
Having git branch outside of blender's ones is a live saver - can't even imagine pushing / pulling branch within blenders one without messing everything sooner or later.

Release cycle is an issue for addons devs, and limited support for images too.
Keeping doc in sync require ways to push in the between.

So definitely a package manager is a must have. (CGcookies addon updater allready make a pretty good job)

Hi, +1 for .rst documentation. But keep in mind that it is one more step added into the addon dev work. In the other hand, allowing external documentation is an alternative as anyone is able to make it the easyest way - and won't require any action (publish rights into wiki and so on). In order to make devs live easyer, you (we) must provide .rst templates as quick starting point, a clear step by step tutorial on how to setup python sphinx package - or creating some "dev toolkit" - so even without rst knowledge anyone is able to kikstart a doc project. Github provide by far easyest ways to contribute with dedicated apps, hiding git logic behind nice gui or even right through web interface, and also provide ways to publish documentation using gh-pages branch (this also allow users to contribute into doc). Having git branch outside of blender's ones is a live saver - can't even imagine pushing / pulling branch within blenders one without messing everything sooner or later. Release cycle is an issue for addons devs, and limited support for images too. Keeping doc in sync require ways to push in the between. So definitely a package manager is a must have. (CGcookies addon updater allready make a pretty good job)

Inês Almeida commented

2018-07-29 18:33:51 +02:00

Added subscriber: @brita

Inês Almeida commented

2018-07-29 18:51:26 +02:00

+1 for campbell's reply
Having the documentation for add-ons in sync with the code change is an interesting idea, but having to understand how to do the doc and adding images or videos is a real problem.

I also agree that dramatic changes can wait to be done together with an add-on package manager,
but! I think that the broken links need to be dealt with ASAP.
I suggest a redirect to the archived wiki in the short term and, if there is no better solution for the 2.8 release, to move over the pages and pamper them a bit, since it won't be possible to update the 2.6 ones in the read-only wiki.

+1 for campbell's reply Having the documentation for add-ons in sync with the code change is an interesting idea, but having to understand how to do the doc and adding images or videos is a real problem. I also agree that dramatic changes can wait to be done together with an add-on package manager, but! I think that the broken links need to be dealt with ASAP. I suggest a redirect to the archived wiki in the short term and, if there is no better solution for the 2.8 release, to move over the pages and pamper them a bit, since it won't be possible to update the 2.6 ones in the read-only wiki.

Tuomo Keskitalo commented

2018-11-12 17:47:01 +01:00

Added subscriber: @TuomoKeskitalo

Tuomo Keskitalo commented

2018-11-12 17:47:01 +01:00

What's the latest news on the fate of add-ons in Blender 2.80?

+1 on package manager idea

What's the latest news on the fate of add-ons in Blender 2.80? +1 on package manager idea

Brendon Murphy commented

2019-06-11 10:36:21 +02:00

@Blendify not sure if this is valid. bug report was wrong place for this.

Francesco Siddi commented

2019-07-19 21:38:10 +02:00

Added subscribers: @brecht, @fsiddi

Francesco Siddi commented

2019-07-19 21:38:10 +02:00

As we are approaching Blender 2.80 release, I'd like to get final confirmation that for the time being add-ons shipped with Blender will be documented on the Blender Wiki. Personally, I want to make sure that the presentation of Blender ID and Blender Cloud add-ons is sufficiently polished and up-to-date.

Can please @brecht or the management team chime in and address the issue?

As we are approaching Blender 2.80 release, I'd like to get final confirmation that for the time being add-ons shipped with Blender will be documented on the Blender Wiki. Personally, I want to make sure that the presentation of Blender ID and Blender Cloud add-ons is sufficiently polished and up-to-date. Can please @brecht or the management team chime in and address the issue?

Brecht Van Lommel commented

2019-07-19 21:40:47 +02:00

The decision was to document add-ons in the Blender manual, not the wiki.

Francesco Siddi commented

2019-07-19 21:52:15 +02:00

Ok, thanks for the clarification. So I assume I'm going to place the add-on docs in manual/addons/.
Is any action required in order to close this issue then?
Do you need any help communicating to all core add-ons developers that documentation should be migrated to the manual?

For context: before writing here I was randomly clicking on some add-ons to see where their documentation would lead, and it was the mostly wiki, redirecting to the legacy wiki.

Ok, thanks for the clarification. So I assume I'm going to place the add-on docs in `manual/addons/`. Is any action required in order to close this issue then? Do you need any help communicating to all core add-ons developers that documentation should be migrated to the manual? For context: before writing here I was randomly clicking on some add-ons to see where their documentation would lead, and it was the mostly wiki, redirecting to the legacy wiki.

Brendon Murphy commented

2019-07-20 04:31:45 +02:00

hi, I would like to add that we could/can do this:
Official addons only to have Manual Pages, there could be exceptions to this, but I think it's a good general rule.
Community Addons to have direct link wiki pages as was the previous behavior. 1 Main "Catalog" page with the current and updated list of addons included in Release only.
We first started this system of addons documentation in the 2.4 series, rebuilt and improved for 2.5/6 series. At the end of the day, https://archive.blender.org/wiki/index.php/Extensions:2.6/Py/Scripts/ was one of the most popular wiki pages visited. I think we could continue with this for 2.8 series. Only devs with commit status would be allowed to edit the wiki after gaining permissions. There's plenty of good sites listing and documenting external addons already.

Result:
"Official" addons would be in the Manual. As Usual.
"Community" addons would be in the Wiki. As Usual.
Manual is kept clean and largely free from changes in content.
Wiki provides the same functionality to host addons pages as it has for years.

I'm prepared to do the bulk of the work and do all the wiki pages @Blendify has been looking at the Manual pages already.
As there's near 80 pages need creating, it's no small job , I can start on this next week,.

Change for the sake of change is not always good, we had a good system, rebuild twice, no reason not do the tried and tested methods again.

hi, I would like to add that we could/can do this: Official addons only to have Manual Pages, there could be exceptions to this, but I think it's a good general rule. Community Addons to have direct link wiki pages as was the previous behavior. 1 Main "Catalog" page with the current and updated list of addons included in Release only. We first started this system of addons documentation in the 2.4 series, rebuilt and improved for 2.5/6 series. At the end of the day, https://archive.blender.org/wiki/index.php/Extensions:2.6/Py/Scripts/ was one of the most popular wiki pages visited. I think we could continue with this for 2.8 series. Only devs with commit status would be allowed to edit the wiki after gaining permissions. There's plenty of good sites listing and documenting external addons already. Result: "Official" addons would be in the Manual. As Usual. "Community" addons would be in the Wiki. As Usual. Manual is kept clean and largely free from changes in content. Wiki provides the same functionality to host addons pages as it has for years. I'm prepared to do the bulk of the work and do all the wiki pages @Blendify has been looking at the Manual pages already. As there's near 80 pages need creating, it's no small job , I can start on this next week,. Change for the sake of change is not always good, we had a good system, rebuild twice, no reason not do the tried and tested methods again.

Inês Almeida commented

2019-07-20 12:44:59 +02:00

I don't think there should be any user documentation in the development wiki.
The wiki is for developers, the manual for users. I think the documentation for all types of add-ons should be together and in the manual.

Edit: committing user documentation with the add-on's code can have advantages, although I'm more inclined to have a separate system that is more focused in high level presentation.
Whichever the workflow, I think user documentation should end up in the manual, not the wiki.

I don't think there should be any user documentation in the development wiki. The wiki is for developers, the manual for users. I think the documentation for all types of add-ons should be together and in the manual. Edit: committing user documentation with the add-on's code can have advantages, although I'm more inclined to have a separate system that is more focused in high level presentation. Whichever the workflow, I think user documentation should end up in the manual, not the wiki.

Brendon Murphy commented

2019-07-22 05:44:23 +02:00

@brita
I'm not a fan of bundling rst docs with addons, the simple way to do this would be to add the doc information to the addons preferences panel within the addon.
That said, It's not an optimal solution and would not provide comprehensive docs that is more focused in high level presentation.
We had designed the wiki catalog with many nice features like documentation progress and templates.
If we can all come to agree I'll start work shortly on this.

My proposal was
Manual: All Official addons. Only the ones with the Blender logo. Manual has always had these addons. Minimum people need access, less can go wrong. No External addons allowed. No External links.
Wiki: Usual Addons Catalog with new rule's that only included in addons or addons contrib are included. Minimum people need access, less can go wrong. No External addons allowed. No External links.
As some addons do have external documentation, this could be handled by the addon itself by using addons preferences and supplying a link to their external documentation in the preferences. Then broken links if/when they eventually happen would be report-able as bugs and not needed to check wiki or manual pages for any links. This did not happen in the old wiki and external links broken was a major issue.

@Blendify
Hi, let's make a decision on this.
If it's preferred by the blender team to have the addons docs in the Manual, let's do it.
I have a few questions on the Manual that we could discuss in blender.chat regards to editing.
https://docs.blender.org/manual/en/dev/addons/index.html
The above page will get quickly messy if 80 addons are added. I would use sub-category's here. Add_Mesh, Add_Curve ect, covering the categories currently used by addons. Each Category would link to a page that has the addons individual listing and docs. These pages could also have sub headings "Official" and "Community". I would not support Contrib addons at this stage. They are not a priority and we could look at them at a later stage.
Main Page Style Could be:
Add Mesh: Listing of Addons that create mesh objects
Import/Export: Listing of Addons that Import or Export file/s to and from Blender
ect.
This would look nice and professional I think.

Thanks.

@brita I'm not a fan of bundling rst docs with addons, the simple way to do this would be to add the doc information to the addons preferences panel within the addon. That said, It's not an optimal solution and would not provide comprehensive docs that is more focused in high level presentation. We had designed the wiki catalog with many nice features like documentation progress and templates. If we can all come to agree I'll start work shortly on this. My proposal was Manual: All Official addons. Only the ones with the Blender logo. Manual has always had these addons. Minimum people need access, less can go wrong. No External addons allowed. No External links. Wiki: Usual Addons Catalog with new rule's that only included in addons or addons contrib are included. Minimum people need access, less can go wrong. No External addons allowed. No External links. As some addons do have external documentation, this could be handled by the addon itself by using addons preferences and supplying a link to their external documentation in the preferences. Then broken links if/when they eventually happen would be report-able as bugs and not needed to check wiki or manual pages for any links. This did not happen in the old wiki and external links broken was a major issue. @Blendify Hi, let's make a decision on this. If it's preferred by the blender team to have the addons docs in the Manual, let's do it. I have a few questions on the Manual that we could discuss in blender.chat regards to editing. https://docs.blender.org/manual/en/dev/addons/index.html The above page will get quickly messy if 80 addons are added. I would use sub-category's here. Add_Mesh, Add_Curve ect, covering the categories currently used by addons. Each Category would link to a page that has the addons individual listing and docs. These pages could also have sub headings "Official" and "Community". I would not support Contrib addons at this stage. They are not a priority and we could look at them at a later stage. Main Page Style Could be: Add Mesh: Listing of Addons that create mesh objects Import/Export: Listing of Addons that Import or Export file/s to and from Blender ect. This would look nice and professional I think. Thanks.

Francesco Siddi commented

2019-07-25 11:39:29 +02:00

From the [Bf-committers] Blender developers meeting notes - 2019-07-22 I see that the process will be coordinated by @meta-androcto.
I missed the conversations on blender chat, so I'm wondering if any decision can be communicated here as well. Thanks!

From the [Bf-committers] Blender developers meeting notes - 2019-07-22 I see that the process will be coordinated by @meta-androcto. I missed the conversations on blender chat, so I'm wondering if any decision can be communicated here as well. Thanks!

Brendon Murphy commented

2019-07-26 04:25:24 +02:00

hi @fsiddi I discussed this briefly with @Blendify and we decided to make the addons documentation a 2.81 target.
After taking into account comments by @brita and the general consensus that "The wiki is for developers, the manual for users" we will do the addons docs in the Manual.
We need to set up rules and guidelines for this.
My thoughts are:
Only Addons from Release get into the Manual, we discussed Addons Contrib but it's not a Priority at this stage. We may look at alternate methods for documenting in contrib addons.
No External addons permitted. We need to keep the Manual clean, readable and usable. It's the Blender Manual and as such should represent the addons shipped with Blender and focus on quality docs and readability.
I found in the past with the 2.4/6/7 addons wiki catalog, external links wasted away, addons were not updated nor pages updated It ended up too much. We can largely prevent this by excluding external addons developers from the manual.

We still have decisions to make on formatting in the Manual.
As you can see here: https://docs.blender.org/manual/en/dev/addons/index.html already there's potential for a wall of addons making readability potentially difficult.
My suggestion here is to use the index page as a Category index. Currently there are 22 categories that addons use in Blender. This is quite a good representation with few addons having a singular listing in a category. I believe I can get this down to 20 with some changes: Example here would be the Matlibvx addon, Currently it is alone in the "Materials" category, it deals with the creation of node trees, it could be put into the nodes category.

I'm also looking at "Who's going to visit here?" For users that have Blender and use the built in addons link to docs, how we format the pages is not important, they will simply link into a page. For users that want to see what Blender has to offer in the way of addons, they may come through the Main manual page or be linked into the main addons page externally. Here it is important we have a good entry point and clean well constructed layout.
it's important we do this right the first time, once we have set infrastructure up, addons authors with commit access will be welcome to participate. I would like to see this done once, with everything in place so there's no confusion for users, writers or developers.

To summarize:
https://docs.blender.org/manual/en/dev/addons/index.html would be main addons page listing 20 categories with each category having a brief description and linking to individual addons pages.
The individual category pages would have the listings of the addons related to their category and matching the "Addons Categories" used in Preferences Addons. This will make each page clean and readable with no difficult walls of text to navigate.

Thanks.

hi @fsiddi I discussed this briefly with @Blendify and we decided to make the addons documentation a 2.81 target. After taking into account comments by @brita and the general consensus that "The wiki is for developers, the manual for users" we will do the addons docs in the Manual. We need to set up rules and guidelines for this. My thoughts are: Only Addons from Release get into the Manual, we discussed Addons Contrib but it's not a Priority at this stage. We may look at alternate methods for documenting in contrib addons. No External addons permitted. We need to keep the Manual clean, readable and usable. It's the Blender Manual and as such should represent the addons shipped with Blender and focus on quality docs and readability. *I found in the past with the 2.4/6/7 addons wiki catalog, external links wasted away, addons were not updated nor pages updated It ended up too much. We can largely prevent this by excluding external addons developers from the manual.* We still have decisions to make on formatting in the Manual. As you can see here: https://docs.blender.org/manual/en/dev/addons/index.html already there's potential for a wall of addons making readability potentially difficult. My suggestion here is to use the index page as a Category index. Currently there are 22 categories that addons use in Blender. This is quite a good representation with few addons having a singular listing in a category. *I believe I can get this down to 20 with some changes: Example here would be the Matlibvx addon, Currently it is alone in the "Materials" category, it deals with the creation of node trees, it could be put into the nodes category.* I'm also looking at "Who's going to visit here?" For users that have Blender and use the built in addons link to docs, how we format the pages is not important, they will simply link into a page. For users that want to see what Blender has to offer in the way of addons, they may come through the Main manual page or be linked into the main addons page externally. Here it is important we have a good entry point and clean well constructed layout. it's important we do this right the first time, once we have set infrastructure up, addons authors with commit access will be welcome to participate. I would like to see this done once, with everything in place so there's no confusion for users, writers or developers. To summarize: https://docs.blender.org/manual/en/dev/addons/index.html would be main addons page listing 20 categories with each category having a brief description and linking to individual addons pages. The individual category pages would have the listings of the addons related to their category and matching the "Addons Categories" used in Preferences Addons. This will make each page clean and readable with no difficult walls of text to navigate. Thanks.

nBurn commented

2019-07-26 10:34:47 +02:00

Added subscriber: @nBurn

Francesco Siddi commented

2019-07-26 15:00:23 +02:00

Sounds good to me @BrendonMurphy! A couple of questions:

Can you take care of porting the core add-ons docs to the manual?
Is any help needed with the definition of the top categories?
Is any help needed with the creation of redirects from the wiki, or do you think it will be possible to update the core add-ons doc link before the release?

Sounds good to me @BrendonMurphy! A couple of questions: * Can you take care of porting the core add-ons docs to the manual? * Is any help needed with the definition of the top categories? * Is any help needed with the creation of redirects from the wiki, or do you think it will be possible to update the core add-ons doc link before the release?

Aaron Carlisle commented

2019-07-27 22:21:05 +02:00

Sorry for the late reply, I have been very busy.

The final decision is to put the official addons in the manual under the existing addons directory.
There has been no final decision on what to do with contrib addons.

Testing addons will not be hosted on blender.org services and we will recommend addon authors solutions, namely Github wiki or read the docs.

For contrib my idea was to either put them in the manual under the existing addons directory in a "contrib" subdirectory.
Alternatively, we can host these add-ons here: http://docs.blender.org/addons-contrib

Sorry for the late reply, I have been very busy. The final decision is to put the official addons in the manual under the existing addons directory. There has been no final decision on what to do with contrib addons. Testing addons will not be hosted on blender.org services and we will recommend addon authors solutions, namely Github wiki or read the docs. For contrib my idea was to either put them in the manual under the existing addons directory in a "contrib" subdirectory. Alternatively, we can host these add-ons here: http://docs.blender.org/addons-contrib

Brendon Murphy commented

2019-08-01 03:35:06 +02:00

Categories for main addons manual page could be as follows:
3D View
"Addons that extend Functionality in the 3d viewport"
Add Curve
"Addons for curve editing and curve object creation"
Add Mesh
"Addons for Mesh Object creation"
Animation
"Addons to help Animation tasks"
Camera
"Addons to help with Camera tasks"
Development
"Addons to help developers with common tasks"
Import/Export
"Here you will find docs for the Importers and Exporters"
Lighting
"Addons to help lighting your scene"
Material
"Addons related to Materials tasks"
Mesh
"Addons relating to the editing of Mesh objects"
Motion Tracking
"Addons to help with motion tracking"
Node
"Addons to help with the Node Editors"
Object
"Addons that provide additional object manipulation methods and tools"
Paint
"Addons to help with Painting tasks"
Pie Menu
"Addons that use Pie Menus as the primary menu type"
Render
"Addons to help with Rendering tasks and Render Engines"
Rigging
"Addons that create new rigs or help with Rigging tasks"
System
"Addons that relate to System Tasks"
UV
"Addons that relate to UV editing tasks"

The above list represents the Current categories that are in use by Release addons.
The descriptions could be improved I guess.
Each category would be a link to a new page with the addons that use the category having their individual pages within.

Addons that need to be ported over are nearly the entire list of addons included in release.

https://docs.blender.org/manual/en/latest/addons/index.html Main Page linking to sub pages
/addons/3d_view sub page with all the 3D View addons listed with links to individual pages/documentation. /addons/3d_view/3d_navigation would be format for sub pages.
We could use: https://archive.blender.org/wiki/index.php/Extensions:2.6/Py/Scripts/3D_interaction/3D_Navigation/ as an example to link to the archived docs until updated pages have been created.
Once a page has been created: /addons/3d_view/3d_navigation and the content if done, the link to old docs would not be needed.

Most all images need to be updated also. Care needs to be taken with naming conventions for addons images.
I would suggest following this for images: "addons"_ "the addons name"_ "single word description.
Example: addons_3d_navigation_ui.jpeg

Thanks.
@fsiddi @Blendify

Categories for main addons manual page could be as follows: **3D View** "Addons that extend Functionality in the 3d viewport" **Add Curve** "Addons for curve editing and curve object creation" **Add Mesh** "Addons for Mesh Object creation" **Animation** "Addons to help Animation tasks" **Camera** "Addons to help with Camera tasks" **Development** "Addons to help developers with common tasks" **Import/Export** "Here you will find docs for the Importers and Exporters" **Lighting** "Addons to help lighting your scene" **Material** "Addons related to Materials tasks" **Mesh** "Addons relating to the editing of Mesh objects" **Motion Tracking** "Addons to help with motion tracking" **Node** "Addons to help with the Node Editors" **Object** "Addons that provide additional object manipulation methods and tools" **Paint** "Addons to help with Painting tasks" **Pie Menu** "Addons that use Pie Menus as the primary menu type" **Render** "Addons to help with Rendering tasks and Render Engines" **Rigging** "Addons that create new rigs or help with Rigging tasks" **System** "Addons that relate to System Tasks" **UV** "Addons that relate to UV editing tasks" The above list represents the Current categories that are in use by Release addons. The descriptions could be improved I guess. Each category would be a link to a new page with the addons that use the category having their individual pages within. Addons that need to be ported over are nearly the entire list of addons included in release. https://docs.blender.org/manual/en/latest/addons/index.html Main Page linking to sub pages /addons/3d_view sub page with all the 3D View addons listed with links to individual pages/documentation. /addons/3d_view/3d_navigation would be format for sub pages. We could use: https://archive.blender.org/wiki/index.php/Extensions:2.6/Py/Scripts/3D_interaction/3D_Navigation/ as an example to link to the archived docs until updated pages have been created. Once a page has been created: /addons/3d_view/3d_navigation and the content if done, the link to old docs would not be needed. Most all images need to be updated also. Care needs to be taken with naming conventions for addons images. I would suggest following this for images: "addons"_ "the addons name"_ "single word description. Example: addons_3d_navigation_ui.jpeg Thanks. @fsiddi @Blendify

Tuomo Keskitalo commented

2019-08-03 16:19:00 +02:00

Suggestions to consider:

Merge "Add Mesh" with "Mesh" and Rename "Add Curve" to "Curve". Reasoning: simpler categorization, unless there is some reason to distinguish between adding and editing?
Rename "Pie Menu" to "UI". Possibly merge "3D View" with "UI". Reasoning: Pie Menu as a high level category may be too specific?

Suggestions to consider: - Merge "Add Mesh" with "Mesh" and Rename "Add Curve" to "Curve". Reasoning: simpler categorization, unless there is some reason to distinguish between adding and editing? - Rename "Pie Menu" to "UI". Possibly merge "3D View" with "UI". Reasoning: Pie Menu as a high level category may be too specific?

Aaron Carlisle commented

2019-08-03 16:38:56 +02:00

Those sound like good suggestions I would also merge Camera into Objects.

Brendon Murphy commented

2019-08-04 04:42:44 +02:00

hi, I'll look at consolidating the categories. One thing to remember we are also providing categories that get used in addons contrib and to set examples for external addons to use rather that clogging up the system.
@TuomoKeskitalo
Add Mesh and Mesh are specific categories, one deals with Object creation, the other with Mesh editing, both are well filled with addons, merging them would create a mess.
Pie Menu to UI is not a bad idea, however, it could also be put into the 3d View category with the other menu/ui addons. This is a reasonable move given there's only 2 pie menu addons, most likely soon to be one and only dealing with the 3d viewport.
@Blendify We could change Camera addons relatively easily, Camera Turn can go to animation and Camera Rigs into Rigging, But then, i'm adding back another "Camera" addon to Contrib soon.
We also have contrib to address, You may have noticed in nightly builds there's "empty" categories in community due to experimental using different categories.
I think it's best to, if we do make changes, think carefully. We don't want less categories with less readability due to too many addons in the one category or grouping unrelated addons into cleverly named categories.

hi, I'll look at consolidating the categories. One thing to remember we are also providing categories that get used in addons contrib and to set examples for external addons to use rather that clogging up the system. @TuomoKeskitalo Add Mesh and Mesh are specific categories, one deals with Object creation, the other with Mesh editing, both are well filled with addons, merging them would create a mess. Pie Menu to UI is not a bad idea, however, it could also be put into the 3d View category with the other menu/ui addons. This is a reasonable move given there's only 2 pie menu addons, most likely soon to be one and only dealing with the 3d viewport. @Blendify We could change Camera addons relatively easily, Camera Turn can go to animation and Camera Rigs into Rigging, But then, i'm adding back another "Camera" addon to Contrib soon. We also have contrib to address, You may have noticed in nightly builds there's "empty" categories in community due to experimental using different categories. I think it's best to, if we do make changes, think carefully. We don't want less categories with less readability due to too many addons in the one category or grouping unrelated addons into cleverly named categories.

Aaron Carlisle commented

2019-12-23 20:57:12 +01:00

Changed status from 'Confirmed' to: 'Resolved'

Aaron Carlisle closed this issue

2019-12-23 20:57:12 +01:00

Aaron Carlisle self-assigned this 2019-12-23 20:57:12 +01:00

Sign in to join this conversation.