Document how to build and change the documentation

[MrPowers]

Expected behavior: Setup instructions on how to build the documentation locally.

Actual behavior: User has to figure out how to build the documentation site locally (it's not hard, but would be easier with instructions).

Suggested change: explain how the user can build a virtual environment with the required dependencies and add contribution instructions on how to build the documentation site locally.

[github-actions]

Thank you for your interest in Apache Sedona! We appreciate you opening your first issue. Contributions like yours help make Apache Sedona better.

[jbampton]

Hi @MrPowers I am just following up on this issue.

More documentation is always nice.

Do you need some help with this issue ?

[jbampton]

refs #1901

[aryn-03]

@jbampton did the issue got solved?

[jbampton]

Hey @aryn-03 more has been done but @MrPowers is assigned to this one

[jbampton]

We now have a section on the website about how to build the docs.

https://sedona.apache.org/latest/setup/compile/#mkdocs-website

But the commands there and re-listed below don't work

uv run mkdocs build
uv run mike deploy --update-aliases latest-snapshot -b website -p
uv run mike serve

After running these 3 commands on a fresh branch from master you get a empty page with a 404 after mike serves on http://localhost:8000/

When you run uv run mkdocs build, it generates a static, single-version site inside your site/ directory.

However, when you immediately follow that with uv run mike deploy, mike completely ignores that site/ folder. Instead, mike looks at your mkdocs.yml, builds the site documentation fresh, and commits it directly to your deployment branch (website) under a specific version folder (like /latest-snapshot/).

Running mkdocs build first is redundant and can occasionally cause local folder confusion if you aren't careful.

This is what I saw from a quick investigation please correct me if I am wrong.

[jbampton]

So when instead of running uv run mike serve you run uv run mike serve -b website

mike then serves on http://localhost:8000/ and when visiting the website loads at http://localhost:8000/latest-snapshot/ but is malformed and looking in the console there are some 404s for JS and CSS

Screen shot of the malformed site:

[jbampton]

Solved the problem. See the screenshot below:

So we had some missing steps from our docs.

The key to get the new site to display properly was found from the docs workflow and running npm install to generate the JS and CSS assets from the gulpfile.js in the docs-overrides directory

https://github.com/apache/sedona/blob/master/.github/workflows/docs.yml

cd docs-overrides && npm ci && npx gulp build
cd .. || exit
uv run mike deploy --update-aliases latest-snapshot -b website -p
uv run mike serve -b website

Also we needed -b website appended to uv run mike serve to get the site to display on localhost

A few more steps like building the Python Sphinx docs and installing the R parts need to be done or documented better and also added to the Makefile for convenience.

I am tagging @Subham-KRLX since he had a lot of trouble on PR #2480 when working on issue #2444 when trying to add the light and dark theme toggle. This should be very easy to implement now.