Repository: bokeh/bokeh

Issue:
Documentation spelling and formatting
There are various typos scattered throughout the documentation.


Discussion:
First batch of fixes was merged in PR #8449. I will leave this issue open to get some more fixes in. Spellchecking shouldn't be limited solely to (sphix) documentation. There are also docstrings, comments in code, strings (e.g. validation messages, exception texts), etc. In the longer term, it would be good to set up spell checking as a part of codebase tests in CI (I will start another issue for that).
After taking another look at the `bokeh.core.validation` module docs, I realized there are two ways classes and modules and such are currently referenced in the docs:

1. Using double backticks:
```rst
``ColumnDataSource``
```

2. Using pipes: `|ColumnDataSource|`, then replaced (using [Sphinx Substitutions](http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions)) at the bottom of the rst file like this:
```rst
.. |ColumnDataSource| replace:: :class:`~bokeh.models.sources.ColumnDataSource`
```

Right now there is a mix of the two in the docs. Everything should be changed to use method 2, since it actually links to the reference for the class/module. 

The downside is that it will be a pain to write all of the substitutions needed for every file. So I'm thinking of standardizing things by putting substitutions for all bokeh classes and modules in the Sphinx `rst_prolog` (not sure about functions, there could be namespace collisions there). There are already a few global substitutions for classes and functions in there.

It would be nice to automate this, instead of manually updating the substitutions every time the bokeh code changes. Writing a simple Sphinx extension to automatically add substitutions would probably be the cleanest way to do this. I haven't looked too hard yet at what it would take to write such an extension.

Let me know if I'm over-engineering things here. It probably makes sense to do this step-by-step anyways, so I'll definitely wait on the automation.

Of course I used method 1 in my pull requests above, so I'd at least like to fix those before closing this issue.
I think putting things in `rst_prolog` is definitely the way to go. I would not be opposed to just using a one-time script to convert mentions of `thing` into `|thing|`, especially since we could update docstrings this way, too (it would be quite a bit harder to make an extension to update docstrings)
Finally had some time to work on this, but I ran into a caveat. I planned on replacing all occurrences of classes ``` ``Thing`` ``` with `|Thing|`, and adding replacement rules for them. However, there some classes with duplicate names:

Name  | Class 1                       | Class 2
----- | ----------------------------- | -------------------------
Color | colors.color.Color            | core.property.color.Color
RGB   | colors.rgb.RGB                | core.property.color.RGB
JSON  | command.subcommands.json.JSON | core.property.json.JSON
Image | core.property.visual.Image    | models.glyphs.Image
Tap   | events.Tap                    | models.tools.Tap

A few ideas to get around this:
1. Make all class replacements include the full path: `|colors.color.Color|`
2. Do (1) for just the 5 classes with duplicate names
3. Don't use replacements, just for the 5 classes with duplicate names.

Any suggestions or opinions?
@mbrown1413 apologies, I lost that there was an open question. For the ones the duplicate names, I would propose:

4) Do short replacements for the right column, and none at all for the left column, except `|events.Tap|` could be worthwhile (the others are all very esoteric and not of general use)


Sounds good. I have most of the replacement commands figured out, so I'll get to this soon.
> There are various typos scattered throughout the documentation.

I love the bokeh charting. I was going through the code, if i encounter such typos shall i correct and send pull request ?
Thanks
@raghavgai PRs for docs corrections are always appreciated
@bryevdv This issue also seems worth working on to me, I have all my day to read and find mistakes and improve them...
Any specific guidelines?? or which is a good place to start from??
@ashwani-rathee For this task, not so much except to read over things at https://docs.bokeh.org with fresh eyes and note all the places you find where there are either typos, or bad formatting, or other editing problems. Then I can help point you to the necessary source files to update to make the changes. 
@bryevdv 
On Creating Layouts page: https://docs.bokeh.org/en/latest/docs/user_guide/layout.html
Under Multiple Objects heading, There is a gibberish message that doesn't make any sense.
 Multiple Objects
Below is a more sophisticated (but fairly typical) example of a nested layout with different sizing modes:
 > Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed elementum lorem lacus, eget scelerisque diam rutrum ac. Nunc est urna, fringilla nec placerat vitae, venenatis egestas eros. Aliquam eleifend orci gravida nulla tempor, sit amet malesuada lacus efficitur. Mauris placerat.
Hey @bryevdv  ,I went through Jupyter notebook tutorials today and I found around 51 spelling mistakes..there are many other tiny-tiny formatting errors (adding/removing a comma, hyphen) and also tiny errors like forms of the verb and use of articles.
@ashwani-rathee The gibberish message is Lorem Ipsum (https://en.wikipedia.org/wiki/Lorem_ipsum) which is commonly used as placeholder text in visual design work. I suppose it's not as widely known as I might think, though, so changing it to something "real" seems like a reasonable thing to do. If you wanted to look at providing more meaningful text, are two places that use Lorem Ipsum in examples:

https://github.com/bokeh/bokeh/search?q=lorem&unscoped_q=lorem

For the tutorial notebooks, those are in a different repo:

https://github.com/bokeh/bokeh-notebooks

To update those you will need to make edits and re-evaluate the notebooks and then save the evaluated notebooks before committing them. It's important to make sure you have the latest release of Bokeh installed when you run the notebooks. I'm not sure if this is enough context, so please let me know if I can provide more information. 


@bryevdv 
For the Multiple layouts one,
I was thinking of replacing lorem ipsum with this:
"In this wave example, the sliders on the left can be used to change the amplitude, frequency, phase and offset of the wave"
For Jupyter Notebooks Changes, What I understood from you and contributing.md is that I have to create an environment according to contributing.md, then activate it and then make the changes...and then rerun them and see that if they show any error or not...if they don't, then I do pullrequest..and am I missing something or need to do anything differently..??

Resolving patch:
diff --git a/sphinx/source/docs/user_guide/examples/layout_sizing_mode_multiple.py b/sphinx/source/docs/user_guide/examples/layout_sizing_mode_multiple.py
--- a/sphinx/source/docs/user_guide/examples/layout_sizing_mode_multiple.py
+++ b/sphinx/source/docs/user_guide/examples/layout_sizing_mode_multiple.py
@@ -40,9 +40,8 @@
 phase.js_on_change('value', callback)
 offset.js_on_change('value', callback)
 
-heading = Div(sizing_mode="stretch_width", height=80, text="Lorem ipsum dolor sit amet, consectetur adipiscing elit. "
-"Sed elementum lorem lacus, eget scelerisque diam rutrum ac. Nunc est urna, fringilla nec placerat vitae, venenatis egestas eros. "
-"Aliquam eleifend orci gravida nulla tempor, sit amet malesuada lacus efficitur. Mauris placerat.")
+heading = Div(sizing_mode="stretch_width", height=80, text="In this wave example, the sliders on the left "
+ "can be used to change the amplitude, frequency, phase and offset of the wave.")
 
 layout = column(heading, row(widgets, plot), sizing_mode="stretch_both")
 


Test patch:
diff --git a/tests/baselines/sphinx/source/docs/user_guide/examples/layout_sizing_mode_multiple b/tests/baselines/sphinx/source/docs/user_guide/examples/layout_sizing_mode_multiple
--- a/tests/baselines/sphinx/source/docs/user_guide/examples/layout_sizing_mode_multiple
+++ b/tests/baselines/sphinx/source/docs/user_guide/examples/layout_sizing_mode_multiple
@@ -1,5 +1,5 @@
 Column bbox=[0, 0, 984, 507]
-  Div bbox=[5, 5, 974, 80]
+  Div bbox=[5, 5, 706, 80]
   Row bbox=[0, 90, 984, 417]
     Column bbox=[0, 0, 150, 250]
       Slider bbox=[5, 5, 140, 53]