Page MenuHome

Proposal: Addon documentation for 2.8
Open, NormalPublic

Description

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.

Details

Type
Bug

Event Timeline

Aaron Carlisle (Blendify) triaged this task as Normal priority.

I can provide a live example if needed.

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.

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)

+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.

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

+1 on package manager idea