mezzanine
mezzanine copied to clipboard
stephenmcd
Improve API Documentation
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
- [ ] 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@c19b41b73559586a7894a7b9fa5e800b6cdfff34
Sounds fantastic - please go right ahead.
One PR should be fine - sphinx.ext.viewcode sounds good too.
@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.
I'm not good in this. can you provide any way following which i can help in this process? @prikhi
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.
@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.
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.
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
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.
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
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 https://github.com/stephenmcd/mezzanine/pull/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 https://github.com/stephenmcd/mezzanine/issues/1148#issuecomment-85413754.
You may just need to select the correct branch on ReadTheDocs(under Admin -> Versions). My branch is 1148-improve-api-docs
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 https://github.com/stephenmcd/mezzanine/issues/1148#issuecomment-85422433.
There's always been a docs mirror on readthedocs - http://mezzanine.readthedocs.org/
How do the Django docs do the versioning?
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.
Regarding #1466 should I continue adding those for the rest of the docs?
