Repository: bokeh/bokeh

Issue:
Sphinx Bokeh Extension Script Directory Sorting
When adding specified directories to the `bokeh_plot_pyfile_include_dirs` the sphinx sorting of the source docs does not properly sort based on the directories or python files containing bokeh.

[This line](https://github.com/bokeh/bokeh/blob/master/bokeh/sphinxext/bokeh_plot.py#L268) seems to be catered specifically to the bokeh doc structure with the 'examples' directory. 

Ideally the sorting should put any directories specified in the sphinx configuration variable `bokeh_plot_pyfile_include_dirs` to be parsed first. I ran into the issue where not all of the python files containing bokeh code would be parsed before the `bokeh-plot` directive in a source doc RST was found which would result in a sphinx error when trying to build.

I was able to get my structure working which has two bokeh source directories under my normal RST source directory so it is something like:

Top level doc repo
--> source
|----> bokeh_dir_1
|----> Rest
|----> Of
|----> RSTs
|----> Z_bokeh_dir_2

I swapped out the previously linked line with:

```python
docnames.sort(key=lambda x: 0 if x.startswith(tuple(env.app.config.bokeh_plot_pyfile_include_dirs)) else 1)
```
This sorting method probably needs improvement, I don't think it will work if the desired directories are in lower depths of directories. 


Discussion:
@hallyourbase would definitely be happy to merge a PR to add a `bokeh_plot_pyfile_include_dirs` (or similar name) config option.
@bryevdv `bokeh_plot_pyfile_include_dirs` is already a config option ([here](https://github.com/bokeh/bokeh/blob/master/bokeh/sphinxext/bokeh_plot.py#L318)), the way the extension handles the sorting based on the contents of the option is the issue. Unless I am misunderstanding your comment.
OK I meant add and use for for sorting, if it already exists, then you are proposing using it for sorting instead of hardcoding "examples" ?
Correct. I think all it needs for proper functionality is the resulting sort to put all of the source bokeh python files in those directories specified in that config variable at the beginning of the `docnames` list so that they get parsed and the associated plot code generated before any `bokeh-plot` directive is reached in RST files which references the python file. That is my current understating anyway. I have not completely become familiar with all the ins and outs of the extension or sphinx extensions in general.
Yes I think that is correct. If you'd like to submit a PR I think that would be easiest for you to test on your end, and would be simple for me to test out on the project docs as well. 

Resolving patch:
diff --git a/bokeh/sphinxext/bokeh_plot.py b/bokeh/sphinxext/bokeh_plot.py
--- a/bokeh/sphinxext/bokeh_plot.py
+++ b/bokeh/sphinxext/bokeh_plot.py
@@ -265,6 +265,9 @@ def run(self):
         return result
 
 def env_before_read_docs(app, env, docnames):
+    # sort to make sure the custom Python file parser gets to process any plot
+    # scripts first, since it will save the plot output for use later.
+    docnames.sort(key=lambda x: 0 if env.doc2path(x).endswith(".py") else 1)
     for name in [x for x in docnames if env.doc2path(x).endswith(".py")]:
         if not name.startswith(tuple(env.app.config.bokeh_plot_pyfile_include_dirs)):
             env.found_docs.remove(name)


Test patch: