enable docs on windows

[mosc9575]

• issues: fixes Docs build on Windows not working #13544

The initial issues are solved on my windows machine but I am getting now an error running the jitter example.

WARNING: Failed to import bokeh.sampledata.commits.
Possible hints:
* AttributeError: module 'bokeh.sampledata' has no attribute 'commits'
* ValueError: time data " 25 Mar 2017 11:32:41 -0500" doesn't match format " %d %b %Y %H:%M:%S %z", at position 19. You might want to try:
    - passing `format` if your strings have a consistent format;
    - passing `format='ISO8601'` if your strings are all ISO8601 but not necessarily in exactly the same format;
    - passing `format='mixed'`, and the format will be inferred for each element individually. You might want to use `dayfirst` alongside this.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.65%. Comparing base (78d71c2) to head (b39e3f5).

Additional details and impacted files

@@             Coverage Diff             @@
##           branch-3.5   #13776   +/-   ##
===========================================
  Coverage       92.65%   92.65%           
===========================================
  Files             326      326           
  Lines           20734    20734           
===========================================
  Hits            19211    19211           
  Misses           1523     1523           

[bryevdv]

@mosc9575 I am not really sure, can you run that example successfully manually?

[mosc9575]

@mosc9575 I am not really sure, can you run that example successfully manually?

It is a bit strange. I can't reproduce the error in a notebook and the output looks allright. But on each run for the docs it show up.
Nethertheless the current solution is not working in the pipeline for the docs, so I have to change something else.

[mosc9575]

After I added format='mixed' temporarily in

bokeh/src/bokeh/sampledata/commits.py

Line 68 in 78d71c2

data.index = cast(Any, pd.to_datetime(data.index, utc=True).tz_convert('US/Central'))

to silence the problem with the scatter_jitter example I was able do build the docs on windows. I hope the docs pipeline will be green as well.

[mosc9575]

I want to mention that the page examples.html is empty in my local build. But I think it is not so important for now.

And I updated two paths. The "examples/models/donut.py" example does not exits anymore and css_classes.py is moved to "examples/styling/dom/css_classes.py" which is at the moment in a folder with is not evaluated.

[tcmetzger]

@mosc9575 Thank you so much for looking into this, having windows docs build back will be great!

When I run make.bat html in this branch on Python 3.10, I still get the webserver starting up (with a 404), before the html build is even finished:

Have you found a way around that?

[mosc9575]

@tcmetzger This error should not apprear if you build the docs from scratch and I belief that you are getting this because of the cached older version of your local docs. Could you please try to run make.bat clean before make.bat html and check if this is working? It was on my windows.

[bryevdv]

Just noting that there's no hard and fast need to have the makefile run docserver.py really. It just seemed convenient to me at the time to make it available via a make target. But docserver.py is just a standard Flask app. If it's simpler or less confusing or error-prone to just have people run python docserver.py for any reason at all we can change the instruction to that instead.

[bryevdv]

@mosc9575 FYI @tcmetzger reported in the weekly meeting that the problem persists even in a completely fresh repo and environment.

[mosc9575]

This are bad news. I thought it is solved, because I can build the docs on my windows using

Python version        :  3.11.8 | packaged by conda-forge | (main, Feb 16 2024, 20:40:50) [MSC v.1937 64 bit (AMD64)]
IPython version       :  8.22.2
Tornado version       :  6.4                                                           
Bokeh version         :  3.5.0.dev1+5.g69c084e6.dirty                                  
BokehJS static path   :  ~\GitHub\bokeh\src\bokeh\server\static
node.js version       :  v20.9.0
npm version           :  10.5.0
jupyter_bokeh version :  (not installed)
Operating system      :  Windows-10-10.0.19045-SP0

I want to describe the problem for the docs on windows again, maybe @tcmetzger can adapt the code in this branch to make it work on his machine.

---

In the code of the bokeh-gallery directive there is a function

bokeh/src/bokeh/sphinxext/bokeh_gallery.py

Line 117 in ca55dcb

def config_inited_handler(app, config):

which loops over all folders listed here

bokeh/docs/bokeh/source/conf.py

Lines 79 to 112 in ca55dcb

	bokeh_example_subdirs = [
	"advanced/extensions",
	"basic/annotations",
	"basic/areas",
	"basic/axes",
	"basic/bars",
	"basic/data",
	"basic/layouts",
	"basic/lines",
	"basic/scatters",
	"styling/visuals",
	"styling/plots",
	"styling/mathtext",
	"styling/themes",
	"interaction/js_callbacks",
	"interaction/legends",
	"interaction/linking",
	"interaction/tools",
	"interaction/tooltips",
	"interaction/widgets",
	"models",
	"plotting",
	"output/webgl",
	"topics/categorical",
	"topics/hierarchical",
	"topics/contour",
	"topics/geo",
	"topics/graph",
	"topics/hex",
	"topics/images",
	"topics/pie",
	"topics/stats",
	"topics/timeseries",
	]

and creates an rst-file for each example in the folder. This could look like

:orphan:

.. index::
   single: examples; wrapping

.. _example_wrapping_advanced/extensions:

wrapping
--------

.. bokeh-plot:: ~\bokeh\examples\advanced\extensions\wrapping.py
    :process-docstring:
    :source-position: below

Later in the process of the build process the bokeh-plot directive will run the code. But there are a few examples which raise an error. To avoid that the rst-file is created, the list below is defiened.

bokeh/docs/bokeh/source/conf.py

Lines 123 to 130 in ca55dcb

	bokeh_sampledata_xref_skiplist = [
	"examples/basic/data/ajax_source.py",
	"examples/basic/data/server_sent_events_source.py",
	"examples/basic/layouts/custom_layout.py",
	"examples/plotting/css_classes.py",
	"examples/models/donut.py",
	"examples/models/widgets.py",
	]

If we can avoid the rst-files for the examples which are listet in the list bokeh_sampledata_xref_skiplist the build will work on windows again.

[tcmetzger]

@mosc9575 I finally was able to do some more testing on different Windows setups - the docs are building as expected!
I apologize for the holdup. I'll merge this right away!

Thank you very much for this PR, not being able to build the docs on Windows has been a major issue for a long time, especially given that editing and building docs should be a low-barrier entry point for anybody who wants to contribute to Bokeh. Getting docs to build on Windows again is a very important win!