CI/DOC: Building documentation with azure

[datapythonista]

• xref Azure CI followup #22766, CI: build documentation for Windows #26574
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[codecov]

Codecov Report

Merging #26591 into master will decrease coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #26591      +/-   ##
==========================================
- Coverage   91.84%   91.84%   -0.01%     
==========================================
  Files         174      174              
  Lines       50644    50644              
==========================================
- Hits        46516    46512       -4     
- Misses       4128     4132       +4

Flag	Coverage Δ
#multiple	90.37% <ø> (ø)	⬆️
#single	41.71% <ø> (-0.09%)	⬇️

Impacted Files	Coverage Δ
pandas/io/gbq.py	78.94% <0%> (-10.53%)	⬇️
pandas/core/frame.py	97% <0%> (-0.12%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7f31865...233b61e. Read the comment docs.

[datapythonista]

This should be ready now. This will build the docs with azure for all CI builds (PRs and master), and will publish them as GitHub pages for master (not for PRs).

I created a repo https://github.com/pandas-dev/pandas-dev.github.io . I made it private, to avoid people getting confused and opening issues or opening PRs for the docs there (it happened in the past with the sphinx theme repo).

The master docs will first be pushed once this is merged. The url to see the docs is: https://pandas-dev.github.io/. The url can easily be changed by a custom domain at: https://github.com/pandas-dev/pandas-dev.github.io/settings (my preference would be to use dev.pandas.io).

In a follow up, we can make sure the docs build on windows too if we want (see #26574). We should just move the new job to ci/azure/docs.yml and call it twice for Linux and Windows. We'll only need to add an extra condition to the publishing of docs, so it's just pushed from Linux.

CC: @pandas-dev/pandas-core @stijnvanhoey

[datapythonista]

@vtbassmatt implemented pandas docs build following your blog post, if you've got any feedback, please let us know.

[TomAugspurger]

Thanks @datapythonista, This looks good.

[jreback]

looks good @datapythonista thanks. note there are a bunch of warnings as well from recent changes, but othogonal.

Let's leave the original job around for a while to make sure this is completely working & updated.

Can change the contributing guide if you'd like now, eg. the path to the built dev-docs (or later ok too)

[datapythonista]

That make sense @jreback, we've got a sprint next week, I'll see if we can get rid of all the warnings in the docs and start validating that they're not reintroduced.

There is a problem with the CI of this change with the ssh key. That couldn't be tested in the PR, since the key is only available for master builds. I'll revert the pushing of the azure in a PR now, while we figure out what's wrong.

[jreback]

@datapythonista the build worked, but the push failed: https://dev.azure.com/pandas-dev/pandas/_build/results?buildId=12093

we might need to disable failing the builds until this is fixed

cc @pandas-dev/pandas-core

[jorisvandenbossche]

I changed travis build to use environment.yml for the docs.

The doc build needs more that what is in that environment (we have additional optional dependencies that are used in the docs), so now a bunch of examples are failing

Please, if you change substantial things about the doc setup, can you at least check the travis / azure logs that things are actually working?

(I fully understand that that is tedious to do before merging each small doc fix, but this one was quite substantial ..)