Skip to content

Build docs and Lite deployment in ReadTheDocs#275

Merged
brichet merged 14 commits intomainfrom
readthedocs
Jan 3, 2025
Merged

Build docs and Lite deployment in ReadTheDocs#275
brichet merged 14 commits intomainfrom
readthedocs

Conversation

@mfisher87
Copy link
Member

@mfisher87 mfisher87 commented Dec 27, 2024

Resolves #208

Hooray! https://jupytergis--275.org.readthedocs.build/en/275/lite/lab/index.html?path=france_hiking.jGIS

Looks like linting is failing unrelated to my change -- perhaps a new release of typescript-eslint modifying detection logic or fixing a bug that was producing false negatives? What's y'all's preference? Deal with the linter errors in this PR or in another PR?

🏗️ Build docs with JupyterLite on ReadTheDocs
💡 Add JupyterLite link to docs index page
🗑️ Remove two bot posts per PR! 🎉 🥳
🦶 New pr-rtd-link.yml automation adds the following footer to each PR:


📚 Documentation preview: https://jupytergis--275.org.readthedocs.build/en/275/
💡 JupyterLite preview: https://jupytergis--275.org.readthedocs.build/en/275/lite/

@mfisher87 mfisher87 added help wanted Extra attention is needed maintenance Fixing lint errors, changing project metadata, changing tooling, changing dependencies, etc. labels Dec 27, 2024
@mfisher87 mfisher87 marked this pull request as draft December 27, 2024 05:47
@github-actions
Copy link
Contributor

Binder 👈 Launch a Binder on branch geojupyter/jupytergis/readthedocs

@github-actions
Copy link
Contributor

github-actions bot commented Dec 27, 2024

Integration tests report: appsharing.space

@mfisher87
Copy link
Member Author

mfisher87 commented Dec 27, 2024

Interesting, the GitHub build is failing for the same reason as the ReadTheDocs build. EDIT: It was my fault for altering docs/environment.yml without understanding its purpose :)

@mfisher87
Copy link
Member Author

mfisher87 commented Dec 27, 2024

I am still confused how I managed to break linting 😆

@mfisher87 mfisher87 force-pushed the readthedocs branch 22 times, most recently from ec975ee to f74e967 Compare December 27, 2024 19:46
@mfisher87
Copy link
Member Author

mfisher87 commented Jan 2, 2025

Since these lint errors require materially changing the readability of the code failing lint, I decided to disable the rule in this PR. a110a11

Do you all feel we should be forbidding the non-null-assertion operator?

cc author of the impacted lines @martinRenou

https://github.com/geojupyter/jupytergis/blame/d5023a2f702982fd176397c7cceca56eff9594df/python/jupytergis_lab/src/notebookrenderer.ts#L79

https://github.com/geojupyter/jupytergis/blame/d5023a2f702982fd176397c7cceca56eff9594df/packages/base/src/formbuilder/objectform/vectorlayerform.ts#L38

Creating multiple environments with mamba exposed lots of problems:

* RTD's default machinery expects a single environment YAML file when
  using conda/mamba. Injecting a 2nd environment into the normal build
  process gets confusing.
* Other hidden assumptions in the default RTD build machinery; I don't
  remember all the problems I ran in to, but getting a working build
  required an unsustainable amount of trial-and-error.
* Default-installed mamba is too old to support 'emscripten' platform,
  needs to be upgraded. When upgrading mamba, ran in to a weird issue
  where the build.html step could not find the python interpreter.

It's possible to fully override build steps, but this is an
_undocumented feature_.

See: readthedocs/readthedocs.org#11551

Instead of overriding build steps, perhaps it will be best long-term to
override the entire build with `build.commands`.

See: https://blog.readthedocs.com/build-customization/
Makes viewing PR previews more accessible!
This feels significantly more intuitive to me.
@mfisher87
Copy link
Member Author

mfisher87 commented Jan 2, 2025

Lint continued to fail with the same errors in CI on the same rule, even after disabling the rule and passing lint on my local machine. I rebased the PR on main and now lint is just failing with no errors in CI. It still passes locally. Any ideas would be very appreciated!

@gjmooney
Copy link
Collaborator

gjmooney commented Jan 2, 2025

Lint continued to fail in CI on the same rule, even after disabling it and passing lint on my local machine. I rebased the PR on main and now lint is just failing with no errors in CI. It still passes locally. Any ideas would be very appreciated!

You need single quotes instead of double quotes in .github/dependabot.yml,
.github/workflows/build.yml, and .github/workflows/pr-rtd-link.yml, and you have extra spaces in docs/environment-docs.yml

If you run jlpm lint locally is should automatically fix those, or jlpm lint:check to get a list of files that need fixing.

@mfisher87
Copy link
Member Author

mfisher87 commented Jan 2, 2025

Thanks all! The lint warnings from eslint were a red herring, and I completely ignored the filenames being output by the prettier check. It's also confusing that jlpm run lint will find errors and apply fixes and return 0 :) Based on previous experience with autofixers, I thought that the check passed and it did nothing!

I posted in #280 that I'd like to move all the formatting checks into pre-commit to avoid the confusing failures in CI. Thoughts?

EDIT: Let's discuss in #281

@mfisher87
Copy link
Member Author

Merge #280 first to fix dependabot config

@brichet
Copy link
Collaborator

brichet commented Jan 3, 2025

@mfisher87 I merged main to trigger again the check-release test.

Copy link
Collaborator

@brichet brichet left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @mfisher87, this looks good to me

@brichet brichet merged commit 90abbb8 into main Jan 3, 2025
10 checks passed
@mfisher87 mfisher87 deleted the readthedocs branch January 3, 2025 16:13
HaudinFlorence pushed a commit to HaudinFlorence/jupytergis that referenced this pull request Jan 28, 2026
* [WIP] Attempt RTD build

* Try building for RTD in an isolated environment

* Restore docs/environment.yml, move docs dependencies to new file

* Upgrade the versions of conda and mamba in RTD build

* Use Micromamba instead of one of the out-of-the-box tool options

Creating multiple environments with mamba exposed lots of problems:

* RTD's default machinery expects a single environment YAML file when
  using conda/mamba. Injecting a 2nd environment into the normal build
  process gets confusing.
* Other hidden assumptions in the default RTD build machinery; I don't
  remember all the problems I ran in to, but getting a working build
  required an unsustainable amount of trial-and-error.
* Default-installed mamba is too old to support 'emscripten' platform,
  needs to be upgraded. When upgrading mamba, ran in to a weird issue
  where the build.html step could not find the python interpreter.

It's possible to fully override build steps, but this is an
_undocumented feature_.

See: readthedocs/readthedocs.org#11551

Instead of overriding build steps, perhaps it will be best long-term to
override the entire build with `build.commands`.

See: https://blog.readthedocs.com/build-customization/

* Add JupyterLite badge and link to docs

* Automate exposing RTD preview link in PR description

Makes viewing PR previews more accessible!

* Make the RTD PR preview link richer

* Ignore the JupyterLite link in the link check automation

* Switch bash commands in YAML from folded to literal blocks

This feels significantly more intuitive to me.

* Format YAML

---------

Co-authored-by: Nicolas Brichet <32258950+brichet@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

help wanted Extra attention is needed maintenance Fixing lint errors, changing project metadata, changing tooling, changing dependencies, etc.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Migrate to ReadTheDocs for more responsive build previews

3 participants