Improve API Documentation

[prikhi]

I would love it if the docs took advantage of some more of Sphinx's features, like cross-references and info field lists: http://sphinx-doc.org/domains.html#the-python-domain

I'm willing to get started on this, I just want to get the sign off before putting any work into it.
Would you prefer a single(squashed?) PR or a PR per app?

And is there opposition to enabling the sphinx.ext.viewcode Sphinx extension? I find this helpful as it keeps me from having to jump between mezzanines docs when I need the overview and the code when I need the details. But I wouldn't be sad if this got shot down, I can always just build them locally...

mezzanine/

• accounts
• blog
• boot
• conf
• core
• forms
• galleries
• generic
• mobile
• pages
• template
• twitter
• utils

docs/

• admin-customization
• blog-importing
• caching-strategy
• colophon
• configuration
• content-architecture
• deplyment
• device-handling
• fabfile
• frequently-asked-questions
• index
• inline-editing
• model-customization
• model-graph
• multi-tenancy
• overview
• packages
• search-engine
• settings
• twitter-integration
• user-accounts
• utilities

This is a lot and my mezzanine dev time is limited so I will be slowly working on this over at prikhi/mezzanine@c19b41b

[stephenmcd]

Sounds fantastic - please go right ahead.

One PR should be fine - sphinx.ext.viewcode sounds good too.

[auvipy]

@prikhi looking forward to it. any update?

[prikhi]

@auvipy I've found myself infinitely busy(as usual). I could quickly add sphinx.ext.viewcode. Since my time is limited, I'll probably do a PR per app, otherwise any progress will take forever to get merged.

If you have a desire to contribute, feel free to submit a PR & reference this issue. I will check off whatever you get in.

[auvipy]

I'm not good in this. can you provide any way following which i can help in this process? @prikhi

[jerivas]

Hey, now that we're talking about this, I would like to suggest we implement something like what the Django docs do. They enable you to view the docs for all versions (1.4, 1.5, 1.6, 1.7, etc), and more importantly, highlight any new features that are introduced in new versions ("New in Django 1.7"). I think Mezzanine could benefit from something like this, specially for developers not staying up to date with the current stable version. There really isn't anything technical about this, is just a matter of making it a convention when new features are documented.

[prikhi]

@auvipy You should check out the sphinx documentation, especially the cross-referencing & info-field list of the python domain:

http://sphinx-doc.org/markup/inline.html
http://sphinx-doc.org/domains.html#cross-referencing-python-objects
http://sphinx-doc.org/domains.html#info-field-lists

"New in" text uses the :versionadded: directive.
http://sphinx-doc.org/markup/para.html#directive-versionadded

Not sure on an easy way to show different versions of the docs, but I know readthedocs.org lets you do this easily.

[stephenmcd]

Hey, now that we're talking about this, I would like to suggest we implement something like what the Django docs do. They enable you to view the docs for all versions (1.4, 1.5, 1.6, 1.7, etc), and more importantly, highlight any new features that are introduced in new versions ("New in Django 1.7"). I think Mezzanine could benefit from something like this, specially for developers not staying up to date with the current stable version. There really isn't anything technical about this, is just a matter of making it a convention when new features are documented.

Awesome idea, wanted to get that working for ages. If anyone feels inclined, please dive in.

[orotau]

Should we use http://readthedocs.org ?
It looks like versioning is built in and it links to GitHub
They support Sphinx https://docs.readthedocs.org/en/latest/index.html
They even give instructions https://docs.readthedocs.org/en/latest/getting_started.html
g

[orotau]

I have had a look at 'read the docs' and managed to get prikhi's version to compile (I had to add a Secret Key to settings.py)
The html is here http://orotau-docs-mezzanine.readthedocs.org/en/latest/
Note the privacy level is set to 'Private' http://docs.readthedocs.org/en/latest/privacy.html
Don't know if any of this is useful.... Await input.

[prikhi]

Does that include #1233? There should be Show Source links in the Packages section(and there are when I build locally):
http://orotau-docs-mezzanine.readthedocs.org/en/latest/packages.html#module-mezzanine.generic

To build docs locally, you need to do something like:

pip install Sphinx
sphinx-build -b html docs _build

[orotau]

mmm I will try again
I thought I forked your version but I am new to github collaboration so
I may have stuffed it up
g

On 24/03/15 22:15, Lysergia wrote:

Does that include #1233
#1233? There /should/ be
|Show Source| links in the |Packages| section(and there are when I
build locally):
http://orotau-docs-mezzanine.readthedocs.org/en/latest/packages.html#module-mezzanine.generic

To build docs locally, you need to do something like:

pip install Sphinx
sphinx-build -b html docs _build

—
Reply to this email directly or view it on GitHub
#1148 (comment).

[prikhi]

You may just need to select the correct branch on ReadTheDocs(under Admin -> Versions). My branch is 1148-improve-api-docs

[orotau]

yep - it's just me being a noob with github
I forked the correct branch but messed up the 'git clone' command (I
think I cloned the 'master' not the 'branch')
g

On 24/03/15 22:33, Lysergia wrote:

You may just need to select the correct branch on ReadTheDocs(under
|Admin -> Versions|). My branch is |1148-improve-api-docs|

—
Reply to this email directly or view it on GitHub
#1148 (comment).

[orotau]

OK hopefully fixed
http://orotau-docs-mezzanine.readthedocs.org/en/latest/

[stephenmcd]

There's always been a docs mirror on readthedocs - http://mezzanine.readthedocs.org/

How do the Django docs do the versioning?

[prikhi]

I get free versioning on readthedocs.org: http://fecwebsite.readthedocs.org/en/latest/

All I did was mark multiple version as "active" under Admin -> Versions.

[auvipy]

is it gonna be complete anytime soon?

[chmelevskij]

Regarding #1466 should I continue adding those for the rest of the docs?

[stephenmcd]

@chmelevskij yes please, it's a huge help