Convert doc-strings for sphinx and add standalone sphinx docs. #117

kporangehat · 2016-05-29T04:51:49Z

This is a large commit almost entirely focused on the doc-strings and related formatting in order to release sphinx docs to replace the wiki.

This also adds some additional consistency to the doc-sting format and layout as well to conform to standards and internal style-guide.

A live preview is available at http://developer.shotgunsoftware.com/python-api/

Some additional consistency to the docsting format and layout as well to conform to standards and internal style-guide.

robblau · 2016-06-01T00:12:44Z

docs/usage_tips.rst

+====
+
+**Smart Cut Fields**: These fields are available only in the browser UI. You can read more about 
+smart cut fields and the API in the Smart Cut Fields doc (link TK)::


Should actually link to the smart cut fields doc.

robblau · 2016-06-01T00:39:49Z

Possible to update the TOC? Currently getting this:

Installation
Authentication
API Usage Tips
Examples
API Reference
Filter Syntax
Data Types
Working With Files (Attachments)
Working With Local Files
Packaging an application with py2app (or py2exe)
Shotgun Server API Changelog

Seems like something along these lines would be a more intuitive ordering:

Installation
Authentication
API Reference
Filter Syntax
Data Types
Examples
API Usage Tips
Working with uploaded files
Working with local files
Packaging an application with py2app or py2exe
Shotgun Server API Changelog (deprecated)

- address CR note for linking to smart cut fields page.

kporangehat · 2016-09-18T21:16:08Z

Ready for CR again.

All docs from the wiki have been added. This version has been pushed to http://developer.shotgunsoftware.com/python-api/

We can probably still improve the organization and update various things (like the svn integration docs... add a github version). But again, the goal here to to get to a point where we can shut down the wiki, then we can iterate on these to get them perfect. 🎉

manneohrstrom · 2016-09-19T08:53:44Z

Suggested feedback before roll-out

This looks amazing. My only real piece high level piece of feedback would be the TOC, which i don't think makes sense right now. It's too flat and it's hard to find things. How about this:

Installation
Authentication
API Reference
-- Shotgun Module Attributes
-- Shotgun()
-- Exceptions
-- Filter syntax
-- Data types
-- Event types
Cookbook
-- API Usage tips
-- Examples
-- Working with files
-- Workfile with local files
-- working with tasks
-- smart cut fields
Advanced
-- Packaging with py2exe
-- Ironpython
-- Server API changelog

The only other piece of feedback i have that I think we should address before an official transition is that the docs currently contain documentation for the internal classes ServerCapabilties and ClientCapabilitites. If they are part of the the official API that we promise never to change, then we should document them for sure. But as far as I understand, these are internal and not intended to be used directly. So they should not be in the sphinx docs. Instead, we should add a warning in the docstrings emphasizing that these classes as part of the internal API and their interfaces may change in the future. Documenting internal classes in the sphinx docs will be confusing to users.

Suggested post-rollout tweaks

Other than that I think it looks amazing: I did a really quick readthrough and jotted down the following feedback - maybe some of this should be considered for a quick subsequent post-doc-transition pass?

manneohrstrom

Here are my suggestions, thoughts and comments:

With the two suggested changes (remove internal classes and TOC rejig to reduce number of high level items) I think this is really to go. It's a huge improvement over the wiki based doc. Amazing work Sir.

I think we should

"soft launch" this by removing the old github wiki docs and replace these with a link to the sphinx docs. Also update developer.shotgunsoftware.com and other places where we reference the docs. We now again have one place to go for docs. And these new docs are fantastic.
Do a post rollout pass where we do further tweaks and see if there are any quick wins and improvements we can make. I added some suggestions in the CR, i am sure there are more tweaks. Once this is done we reach out to the shotgun-dev list and let them know about the change.

kporangehat · 2016-09-19T13:06:11Z

@manneohrstrom great notes! What were you referring to by this one?

Would be great with some more complex filter examples. Maybe these could be moved across into the "cookbook"

manneohrstrom · 2016-09-19T14:08:58Z

@kporangehat in the filter syntax section, you currently have this:

I think what would be great would be to:

move the examples into the "cookbook" section and put a reference in the docs so that people can jump easily from the reference docs (e.g. the location above) to the cookbook.
in the cookbook, have a collection of examples, showing different ways to combine things
maybe add a number of example both of basic and advanced syntax.
what would be ideal is if there is a cut'n'paste ready example for most common patterns, so that a TD could quickly grab some code straight out of the docs and transform it into something specifically for them.
examples with nested query syntax would be great with the cookbook syntax. Also a screenshot showing how you can hover over a location in the shotgun fields list and see its nested API syntax. This is a lesser known feature and it's extremely useful.
In fact, in general it might be great to have a section to answer the following
- Where do i go to see what entity types I can use in the API?
- How do i find the name of a field i want to use?

Users shouldn't rely on these as they are internal and can change at any time.

- reorganized TOC - some files were moved or combined for better organization - removed docs for ServerCapabilities and ClientCapabilities as they are internal classes that may change at any point - added Cookbook section as a container for detailed usage examples. - split up Shotgun class methods into logical groups of methods. - added link from Event Types docs to the shotgunEvents event daemon repo - updated working in Event Types. - added warning to Smart Cut Fields about it's deprecation with a link to Cut Support in Shotgun v7 - Modified date in Shotgun Server API Changelog to be more internationally understood - Renamed "Working with Local Files" to "Working with the Local File type" as part of the Working With Files docs to make it slightly ? clearer. - Moved Iron Python info to the advanced section - Re-ordered installation sections to have manual Github install instructions at the top and pip instructions underneath - Lots of other misc tweaks and edits.

kporangehat · 2016-09-19T21:16:03Z

Pushed and built a new version at http://developer.shotgunsoftware.com/python-api/

Addressed most of the things you brought up above (marked with ✅ ).

Outstanding items:

Complex filter examples as well as additional "cut-n-paste" examples in the cookbook.

Neil is working on some of these and I'll coordinate with him to get them added to the right place. I think that the single examples were relevant still in the doc so I left them there for now.
New in version / Requires Shotgun Server info updates.

I added these as I went and some of them got very irrelevant but I kept them in for the time being. We can remove stuff that's old enough. I like the idea here, but making it actually relevant would be better.
Automated builds of the docs.

Working on this one.
FAQ section for things like how to get the system name / dot-notation of linked fields, etc.

Perhaps we can start compiling a list.
Lots of additional cleanup and tweaks 🚜

robblau

This all looks good. The one thing I think should be changed is that an actual link to the changelog section of the readme on github should be added to the index.

Potentially we could even get rid of the changelog section in the developer docs if they really are out of date and redundant. Other than that, AWESOME stuff.

kporangehat · 2016-09-20T00:41:53Z

What do you think about moving that changelog to its own CHANGELOG file?

KP
Shotgun | Autodesk

From: Rob Blau notifications@github.com notifications@github.com
Reply: shotgunsoftware/python-api
reply@reply.github.com
reply@reply.github.com
Date: September 19, 2016 at 7:38:51 PM
To: shotgunsoftware/python-api python-api@noreply.github.com
python-api@noreply.github.com
CC: KP kp@shotgunsoftware.com kp@shotgunsoftware.com, Mention
mention@noreply.github.com mention@noreply.github.com
Subject: Re: [shotgunsoftware/python-api] Convert doc-strings for sphinx
and add standalone sphinx docs. (#117)

@robblau commented on this pull request.

This all looks good. The one thing I think should be changed is that an
actual link to the changelog section of the readme on github should be
added to the index.

Potentially we could even get rid of the changelog section in the
developer docs if they really are out of date and redundant. Other than
that, AWESOME stuff.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#117 (review),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAANP6AzUK82cDfgEDR4mvo9Zwmb3x8Qks5qrysagaJpZM4IpNrT
.

robblau · 2016-09-20T00:49:42Z

I'd be game for that. Feels pretty equivalent, but he docs should have an easy to find pointer to them.

- Changelog is now published in the docs as well as included as a HISTORY.rst file in the repo.

- Removed the server changelog info as it was out of date and not very useful.

Convert docstrings for sphinx and add standalone sphinx docs.

461605e

Some additional consistency to the docsting format and layout as well to conform to standards and internal style-guide.

robblau reviewed Jun 1, 2016
View reviewed changes

KP added 14 commits September 17, 2016 12:24

rename section to just "Working with Files"

a514ed9

addressing CR, re-organize TOC

735483a

adds smart cut fields, and task docs

51da9e7

- address CR note for linking to smart cut fields page.

add current_module

9198bfe

Merge branch 'master' into sphinx_docs

64368e3

add note about thread safety

f90e031

add additional_filter_presets documentation

79347e2

Add missing docs from Wiki

f9c38a5

Move task info to its own directory

5c5bf18

remove reference to pypi for now...

726f2dc

Add info about ConnectionEntities

0ba5b8c

move tasks to its own page and add event_types

4488092

reorganize and link up new docs (removed some too)

c8db098

[minor] Changelog formatting fixes.

2a31ad4

kporangehat assigned manneohrstrom and robblau Sep 18, 2016

manneohrstrom approved these changes Sep 19, 2016

View reviewed changes

KP added 4 commits September 19, 2016 15:37

add warning about these being internal classes.

32b2efd

Users shouldn't rely on these as they are internal and can change at any time.

link additional_filter_presets param description to docs

eba2d3a

minor fix to class reference syntax

af73a31

robblau reviewed Sep 20, 2016

View reviewed changes

KP added 3 commits September 20, 2016 14:25

update README and move changelog to separate file

b5b7339

- Changelog is now published in the docs as well as included as a HISTORY.rst file in the repo.

Some reorganization and cleanup.

4b9845e

- Removed the server changelog info as it was out of date and not very useful.

Remove a level from the TOC to keep it clean

ce469a7

kporangehat closed this in b5138d6 Sep 22, 2016

jfboismenu deleted the sphinx_docs branch April 5, 2018 00:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Convert doc-strings for sphinx and add standalone sphinx docs. #117

Convert doc-strings for sphinx and add standalone sphinx docs. #117

Uh oh!

kporangehat commented May 29, 2016

Uh oh!

robblau Jun 1, 2016

Uh oh!

robblau commented Jun 1, 2016

Uh oh!

kporangehat commented Sep 18, 2016

Uh oh!

manneohrstrom commented Sep 19, 2016 •

edited by kporangehat

Loading

Uh oh!

manneohrstrom left a comment

Uh oh!

kporangehat commented Sep 19, 2016

Uh oh!

manneohrstrom commented Sep 19, 2016

Uh oh!

kporangehat commented Sep 19, 2016

Uh oh!

robblau left a comment

Uh oh!

kporangehat commented Sep 20, 2016

Uh oh!

robblau commented Sep 20, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Convert doc-strings for sphinx and add standalone sphinx docs. #117

Convert doc-strings for sphinx and add standalone sphinx docs. #117

Uh oh!

Conversation

kporangehat commented May 29, 2016

Uh oh!

robblau Jun 1, 2016

Choose a reason for hiding this comment

Uh oh!

robblau commented Jun 1, 2016

Uh oh!

kporangehat commented Sep 18, 2016

Uh oh!

manneohrstrom commented Sep 19, 2016 • edited by kporangehat Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Suggested feedback before roll-out

Suggested post-rollout tweaks

Uh oh!

manneohrstrom left a comment

Choose a reason for hiding this comment

Uh oh!

kporangehat commented Sep 19, 2016

Uh oh!

manneohrstrom commented Sep 19, 2016

Uh oh!

kporangehat commented Sep 19, 2016

Uh oh!

robblau left a comment

Choose a reason for hiding this comment

Uh oh!

kporangehat commented Sep 20, 2016

Uh oh!

robblau commented Sep 20, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

manneohrstrom commented Sep 19, 2016 •

edited by kporangehat

Loading