Repository: Parsl/parsl

Issue:
Tweak documentation organization
The documentation is already in awesome shape-- this is just a minor thing that occurs to me while reading through it. We currently have class documentation under `Developer documentation` -> `Developer documentation`. I think we should reorganize that a bit to remove the redundancy. We currently have a very nice layout:

1. Quickstart
2. User guide (includes overview, detailed descriptions of various components, FAQ)
3. Developer documentation

As a new user, you'd probably see 'Developer documentation' and assume that was for Parsl devs only. But class documentation for user-facing classes is clearly relevant for them too. Sometimes, especially users that are relatively familiar with Parsl, but want to quickly figure out what the options are for a particular class want to quickly look up the class documentation and not have to search through the detailed descriptions. I vote to add a fourth section, after the User guide, called `Class documentation` or similar, which only contains the class documentation.


Discussion:
Note that switching to making the class documentation more user-facing has an added benefit: it will not need to be synced with the documentation. For example, [here](https://parsl.readthedocs.io/en/latest/userguide/apps.html#special-keywords-arguments) the documentation is out-of-sync with the class signature. We should just make the docstring in the class signature clear enough that it does not need to be repeated there.
@yadudoc I'm thinking we can split up the class documentation into classes that are relevant for users (`PythonApp`, etc) which go in the user class documentation, and classes that aren't (`AppBase`, etc), which go in the developer documentation. The point is to make it easy for users to find the class documentation which is relevant to them. Does that sound reasonable?
I'd take a second opinion on this. Several projects like ipyparallel, boto, and even the C Programming Language book start with a beginners section followed by the reference section. My worry is that we'll make the userguide needlessly tedious by pushing class docs into it. For eg, classes documentation like the DFK contain info on methods that the user is never expected to use. The pythonApp class is simple because it has very few methods.

At it's core parsl does just a few things, I hope that the userguide is easy to run through and I worry that for a new user adding class docs may not help in the initial reading.

If the doc is outdated, that's a doc bug. The user facing docs still have to be written and maintained, and we realistically can rely on the class docs only as a supplement, esp for a new user. 

Perhaps we could either link, or include just specific interfaces rather than the class definition ?


> I'd take a second opinion on this. Several projects like ipyparallel, boto, and even the C Programming Language book start with a beginners section followed by the reference section. 

I think we're in complete agreement! I do not think the class documentation should be a part of the user guide. I think it should be its own section labelled 'Reference guide' or 'API guide' or something like that. Currently they are hidden under `Developer documentation -> Developer documentation` such that we're basically saying: 'user, this is not relevant for you.' But often a non-beginner user just wants a fast place they can go to just see what all of the options are (they do not want to read through all of the explanations because they already know them, they just want to look it up.) This is why I think it makes sense to have the class documentation in its own section, _without_ any additional verbage, such that some can quickly find the signature for a given class. Something like:

1. Quickstart
2. User guide (includes overview, detailed descriptions of various components, FAQ)
3. Reference guide (this is what I'm proposing adding)
4. Developer documentation

Having a separate reference guide is the standard on most projects I have used. See [matplotlib](https://matplotlib.org/contents.html), [ROOT](https://root.cern.ch/doc/master/modules.html) for example.
[IPython](http://ipython.readthedocs.io/en/stable/api/index.html) does this too.
Maybe 'Class index' would be better than 'Reference guide', since it actually describes what it is.

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -33,8 +33,19 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.linkcode'
 ]
 
+def linkcode_resolve(domain, info):
+    if domain != 'py':
+        return None
+    if not info['module']:
+        return None
+    filename = info['module'].replace('.', '/')
+    return "http://github.com/Parsl/parsl/blob/master/{}.py".format(filename)
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -89,7 +100,7 @@
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 #
-# default_role = None
+default_role = 'all'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #
diff --git a/parsl/__init__.py b/parsl/__init__.py
--- a/parsl/__init__.py
+++ b/parsl/__init__.py
@@ -42,7 +42,10 @@
 __author__ = 'Yadu Nand Babuji'
 __version__ = VERSION
 
-__all__ = ['App', 'DataFlowKernel', 'File', 'ThreadPoolExecutor', 'IPyParallelExecutor']
+__all__ = [
+    'App', 'DataFlowKernel', 'File', 'ThreadPoolExecutor',
+    'IPyParallelExecutor', 'set_stream_logger', 'set_file_logger'
+]
 
 
 def set_stream_logger(name='parsl', level=logging.DEBUG, format_string=None):


Test patch: