Add docs build job

[AyodeAwe]

The PR adds a docs_build process to the PR and Build workflows for this repository. The generated docs are synced to s3 for only the build workflows.

[codecov-commenter]

Codecov Report

Base: 92.60% // Head: 92.60% // No change to project coverage 👍

Coverage data is based on head (1a203c1) compared to base (870b164).
Patch has no changes to coverable lines.

Additional details and impacted files

@@              Coverage Diff              @@
##           branch-23.02     #868   +/-   ##
=============================================
  Coverage         92.60%   92.60%           
=============================================
  Files                24       24           
  Lines              1014     1014           
=============================================
  Hits                939      939           
  Misses               75       75           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[ajschmidt8]

Looks good. Added a few comments

[AyodeAwe]

Warning, treated as error:
/opt/conda/envs/docs/lib/python3.9/site-packages/cuspatial/core/geoseries.py:docstring of cuspatial.core.geoseries.GeoSeries.contains_properly:39:Unexpected indentation.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[thomcom]

Are these inline pydocs changes purposeful? I ask because it seems like there would be a lot more changes across the codebase to match the new formatting requirement, if there is one.

[ajschmidt8]

Are these inline pydocs changes purposeful? I ask because it seems like there would be a lot more changes across the codebase to match the new formatting requirement, if there is one.

@thomcom, we've enabled the -W flag for the Sphinx builds, which treats warnings as errors (e.g. these).

It seems like there are only 11 warnings and they all look whitespace related, so it shouldn't be too hard for us to address them in this PR.

If it gets out of hand, we can address them in a follow-up PR.

[ajschmidt8]

I've just pushed a few additional changes and some reversions.

I think this is almost the minimum set of changes needed to build the docs without any warnings.

I'm expecting the latest commit as of this writing (4f60b18) to throw a duplicate label error from the autosectionlabel plugin.

Once that happens, I will push the change below to suppress it since it's a relatively benign warning.

suppress_warnings = [
    "autosectionlabel.*"
]

It stems from the fact that the https://docs.rapids.ai/api/cuspatial/nightly/user_guide/cuspatial_api_examples.html page has two section headers called cuspatial.polygon_bounding_boxes.

As a result of this, the first occurrence gets a correct anchor attached, but the second occurrence gets an anchor of #id1. See here:

• https://docs.rapids.ai/api/cuspatial/nightly/user_guide/cuspatial_api_examples.html#cuspatial.polygon_bounding_boxes
• https://docs.rapids.ai/api/cuspatial/nightly/user_guide/cuspatial_api_examples.html#id1

The consequence of this is that you can't confidently link to either section using the :ref: syntax outlined in the autosectionlabel docs since there is a duplicately named section.

However, I didn't see any instances of :ref: being used anywhere.

@thomcom, I'll defer to you to determine if you want to leave the suppress_warnings entry or properly address the warning in a follow-up PR.

[ajschmidt8]

We can also just remove the autosectionlabel plugin to fix this issue. I'm not sure what effect that will have on the rendered docs.

I will check that locally.

[thomcom]

I'd be interested in addressing the warnings in a follow up PR, we can chat about how to get my pre-commit set up to give me docs warnings in addition to the normal commit errors. Given that cuspatial.polygon_bounding_boxes is already defined in its own section, I'm ok with dropping that from the list of three functions under Indexed Spatial Joins.

[ajschmidt8]

@thomcom, I just pushed two changes based on your reply.

Can you review / approve this PR when you have a moment? It should be good to go now.

[ajschmidt8]

/merge