Re: [GMG-Devel] How to contribute to documentation

[Christopher Allan Webber]

Heya Laura!  I'm so sorry this took me so long to get to... no excuse
except the holidays getting insane I gues.

Laura Arjona Reina writes:

> Hi everybody
>
> http://mediagoblin.readthedocs.org has been great help to setup my GNU
> MediaGoblin instances. Thank you very much for the software and the
> documentation, and the additional help in the IRC channel :)
>
> I've seen the "Core Plugin Documentation part" and now it shows:
>
> Part 2: Core plugin documentation
>
>     flatpagesfile plugin
>     sampleplugin
>     Trim whitespace plugin
>     raven plugin
>     basic_auth plugin
>     openid plugin
>     persona plugin
>     ldap plugin
>
> Since I'm trying some plugins in my site, I suppose I can contribute to
> the documentation at least listing the current list of plugins, and
> maybe writing a bit about the plugins that I'll use in my site.
>
> I'm running 0.7.1 and my plugin folder has, in addition to the files
> that are already listed, these ones:
>
> api (is this a plugin? not sure)
> metadata_display
> archivalook
> geolocation
> oauth
> piwigo
> httpapiauth
>
> So my first contribution to the docs would be to list all the plugins,
> and in alphabetical order, if nobody points to a better order.

I think that sounds great!

> But, how to do that? Do I just contribute as in code, creating my branch
> from the "master" branch, and working in the /docs/source folder? or do
> I need to make a branch/contribution for each tag?

Yes, contribute the same way you would for code.

Everything starts in mediagoblin/docs/source/index.rst, and references
files from there.

You can test the documentation before you push live:

  $ cd ~/devel/mediagoblin   # or wherever
  $ source bin/activate      # activate the virtualenv
  $ easy_install sphinx      # if not already installed
  $ cd docs
  $ make html
  $ iceweasel build/html/index.html

> And about the issue tracker: do I open a ticket "Update core plugins
> documentation"? Or one ticket for each plugin?

You could do a single branch with all those updates, and add a ticket
with a link to that branch.  Set the category to "documentation."

> I will update the wiki page
> https://wiki.mediagoblin.org/Documentation_quick_start to reflect what I
> learn.

Stellar!

> Thanks

Thank *you*, Laura! :)  Sorry again this took so long.
 - Chris