Add Readthedoc feature #15

shenvitor · 2024-06-04T16:21:36Z

Make it now have both GitHub documentation and RTD build

shenvitor · 2024-06-04T16:28:03Z

I want to add this...
and I have authorised in : https://readthedocs.org/projects/gluex-nstar/

seems like it is necessary to add the .readthedocs.yaml file, and that is enough(?) @redeboer

redeboer · 2024-06-04T16:43:15Z

Fancy! Not sure if RTD is really needed. Usually it is used for packages that need versioning (so a page per version, e.g. https://qrules.rtfd.io/0.10.1). Another benefit is PR previews. If you don't need those, GitHub Pages suffices. (GH has the benefit that it can cache e.g. notebook results and sympy caches.)

redeboer · 2024-06-04T16:45:22Z

But let's discuss tomorrow, there is something to say for using RTD ✨

shenvitor · 2024-06-04T20:30:00Z

Fancy! Not sure if RTD is really needed. Usually it is used for packages that need versioning (so a page per version, e.g. https://qrules.rtfd.io/0.10.1). Another benefit is PR previews. If you don't need those, GitHub Pages suffices. (GH has the benefit that it can cache e.g. notebook results and sympy caches.)

Yup actually I wanna have PR preview, that's why I wanna add it :)

shenvitor · 2024-06-06T13:08:33Z

OK, now I understand. Maybe "rtd" is not necessarily appropriate here, but I'll decide later and make this work first. Seems like it is Okish

redeboer · 2024-06-06T14:30:47Z

Have a look at the log output. The config is looking for docs/source/conf.py, not docs/conf.py
https://readthedocs.org/projects/gluex-nstar/builds/24613998/

shenvitor · 2024-06-06T14:41:25Z

Interestingly... I see at some point the readthedoc is okay but the Github pages failed :(
https://readthedocs.org/projects/gluex-nstar/builds/24613277/
Not sure if I can have both(?)
extension of mystnb and sphinx of readthedoc

shenvitor · 2024-06-07T09:34:25Z

Man.... Finally now in this version both the GitHub documentation and RTD are working :)
(waiting for approval @redeboer 🐳)

redeboer

Good job!
There are some files that seem redundant to me, have a look at the comments ;)

docs/conf.py

redeboer · 2024-06-07T18:19:08Z

docs/requirements.txt

@@ -0,0 +1,4 @@
+linkify-it-py


I don't like this duplication of dependencies. Indeed RTD by default expects dependencies to be defined through pip requiremente files, but you can define custom build steps. In this case to specify you want to run pixi shell before the build process. Have a look at e.g. https://github.com/ComPWA/ampform for how a custom build (in that case with pip constraint files) looks like.

I see... right now kinda stuck in here 🐥

.github/workflows/ci-docs.yml

docs/conf.py

docs/make.bat

redeboer · 2024-06-07T20:51:45Z

pyproject.toml

@@ -0,0 +1,8 @@
+[build-system]


Was this required by rtd? If so, I would convert pixi.toml to pyproject.toml
https://pixi.sh/latest/advanced/pyproject_toml

I removed and it works.

redeboer · 2024-06-11T20:20:06Z

.readthedocs.yaml

+    post_install:
+      - curl -fsSL https://pixi.sh/install.sh | bash
+      - export PATH="$HOME/.pixi/bin:$PATH" && pixi install
+      - pixi shell -c "pixi install && sphinx-build -T -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html"


Unfortunately, RTD runs its own sphinx-build command (hence pre_build, post_build, not build itself). So just running pixi shell should suffice 🤞 If it doesn't, this may be a more tricky issue to solve...

Btw pixi install is not needed, at most pixi shell

Unfortunately, RTD runs its own sphinx-build command (hence pre_build, post_build, not build itself). So just running pixi shell should suffice 🤞 If it doesn't, this may be a more tricky issue to solve...

Seems like it doesn't, maybe tricky? What if the pixi shell an interactive shell which is not supported in the ReadTheDocs environment, maybe?

e.g. this issue in RTD build indicates that it probably can't start an interactive shell there:

https://readthedocs.org/projects/gluex-nstar/builds/24669635/

redeboer · 2024-06-11T20:20:30Z

build-docs.sh

@@ -0,0 +1,3 @@
+#!/bin/sh


This file can be removed, right?

yup originally just testing

docs/conf.py

redeboer · 2024-06-11T20:25:22Z

pixi.toml

 myst-nb = ">=1.1.0,<1.2"
+myst-parser = ">=3.0.1,<3.1"
+nbsphinx = ">=0.9.4,<0.10"


I would use myst-nb instead of nbsphinx (that's a different notebook renderer). That also removes the need for myst-parser, maybe also that linkify-md thing, because those are indirect dependencies of myst-nb

Actually, why are dependency changes required in this PR?

I added them when I added RTD from their example

redeboer · 2024-06-11T20:26:12Z

pixi.toml

 sphinx-autobuild = ">=2024.4.16,<2024.5"
+sphinx_rtd_theme = ">=2.0.0,<2.1"


Are you selecting that in conf.py?

redeboer · 2024-06-11T20:26:36Z

docs/index.md

+
+Investigation of the N\* Resonances in the GlueX Experiment
+
+> **Note:** This project is under active development.


I would use a MyST admonition here

redeboer · 2024-06-11T20:28:05Z

docs/conf.py

+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+html_theme = "sphinx_rtd_theme"


This theme change is not required on RTD. Also works with what you had before.

…pre_biild

redeboer · 2024-06-12T19:48:01Z

Hmm seems that this is a bit more complicated then expected. I think the best way forward is to convert pixi.toml to pyproject.toml, so that the dependencies can be installed through pip (or uv) directly (which RTD requires/prefers). But let's look at that once I'm back

redeboer · 2024-06-14T22:04:44Z

@shenvitor check this newpixi release. There are some examples now of how to use pixi in Read the Docs:
https://github.com/prefix-dev/pixi/blob/main/examples%2Freadthedocs-override%2F.readthedocs.yaml

redeboer · 2024-06-17T12:46:37Z

I think you can replace the entire .readthedocs.yml with this part:
https://github.com/prefix-dev/pixi/blob/f8f84d305673976600689aca74d8bdc312b63561/examples/readthedocs-override/.readthedocs.yaml#L1-L10
Of course, do replace the docs task name with docnb.

Forget the last line with pixi run readthedocs for now. Maybe we need some modification of that task later on, but let's see if it works without.

redeboer

Awesome

add readthedoc yaml file

3845af3

shenvitor self-assigned this Jun 4, 2024

shenvitor requested a review from redeboer June 4, 2024 16:22

shenvitor added the 🖱️ DX Improvements to the Developer Experience label Jun 4, 2024

shenvitor added 5 commits June 6, 2024 15:21

add essential set-up files if using rtd

52bbc60

more essential set-up files if using rtd

5e5a047

directory specification

3d345c2

location rename

1f6e247

install rtd theme

95f69ce

shenvitor marked this pull request as draft June 6, 2024 13:52

shenvitor added 3 commits June 6, 2024 15:56

rst file

2892baa

hello

9d6d073

hello world

05ebb94

yaml file confy file location

0ea61f2

shenvitor added 5 commits June 7, 2024 10:48

adjust to mystnb

a20a5de

Adjust configuration for RTD

99fe394

Ensure _static directory exists

a5ed974

add python version in git workflow ci file

85f269e

Ensure _static directory exists with a .keep file

b227762

shenvitor marked this pull request as ready for review June 7, 2024 09:34

make _templates directory exists with a .keep file

1635fc9

redeboer requested changes Jun 7, 2024

View reviewed changes

shenvitor added 5 commits June 11, 2024 17:49

stucks here

5d2025d

add build_commends maybe

bd5d1e2

again post build maybe

dd52c07

add back python maybe

8a9dbde

wrap into post_install

e63b382

redeboer requested changes Jun 11, 2024

View reviewed changes

shenvitor added 8 commits June 12, 2024 11:06

add pre_biild

980f254

add install before pre_biild

8e35409

try only pixi shell in pre_biild

5523780

attempt to run command bypassing the need of an interactive shell in …

6a051d7

…pre_biild

only pixi shell and then python

e5992b4

Add back pyproject again

0ca76fa

remove build-docs.sh

c2c8b15

remove pyproject again

d760eeb

shenvitor changed the title ~~Add Readthedoc~~ Attempt: add Readthedoc Jun 12, 2024

This comment has been minimized.

Sign in to view

shenvitor added 2 commits June 17, 2024 14:56

update .readthedoc.yaml by an example

f7231ef

reduce diff with main branch

5c3746c

shenvitor force-pushed the readthedoc branch from 4f1c095 to 5c3746c Compare June 17, 2024 13:22

shenvitor added 3 commits June 17, 2024 15:23

Merge branch 'main' into readthedoc

653cd5f

remove cell timeout and print traceback

418daad

move html output to RTD location

7fee9c9

shenvitor changed the title ~~Attempt: add Readthedoc~~ Add Readthedoc feature Jun 17, 2024

redeboer approved these changes Jun 17, 2024

View reviewed changes

shenvitor marked this pull request as ready for review June 17, 2024 13:52

shenvitor merged commit 5b088f2 into main Jun 17, 2024
4 checks passed

shenvitor deleted the readthedoc branch June 17, 2024 13:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Readthedoc feature #15

Add Readthedoc feature #15

shenvitor commented Jun 4, 2024 •

edited

Loading

shenvitor commented Jun 4, 2024 •

edited

Loading

redeboer commented Jun 4, 2024

redeboer commented Jun 4, 2024

shenvitor commented Jun 4, 2024

shenvitor commented Jun 6, 2024 •

edited

Loading

redeboer commented Jun 6, 2024

shenvitor commented Jun 6, 2024 •

edited

Loading

shenvitor commented Jun 7, 2024 •

edited

Loading

redeboer left a comment

redeboer Jun 7, 2024

shenvitor Jun 11, 2024

redeboer Jun 7, 2024

shenvitor Jun 11, 2024

redeboer Jun 11, 2024

redeboer Jun 11, 2024

shenvitor Jun 12, 2024 •

edited

Loading

shenvitor Jun 12, 2024

redeboer Jun 11, 2024

shenvitor Jun 12, 2024

redeboer Jun 11, 2024

redeboer Jun 11, 2024

shenvitor Jun 12, 2024

redeboer Jun 11, 2024

shenvitor Jun 12, 2024

redeboer Jun 11, 2024

redeboer Jun 11, 2024

redeboer commented Jun 12, 2024

redeboer commented Jun 14, 2024 •

edited

Loading

This comment has been minimized.

redeboer commented Jun 17, 2024 •

edited

Loading

redeboer left a comment

		sphinx-autobuild = ">=2024.4.16,<2024.5"
		sphinx_rtd_theme = ">=2.0.0,<2.1"


		Investigation of the N\* Resonances in the GlueX Experiment

		> Note: This project is under active development.

Add Readthedoc feature #15

Add Readthedoc feature #15

Conversation

shenvitor commented Jun 4, 2024 • edited Loading

shenvitor commented Jun 4, 2024 • edited Loading

redeboer commented Jun 4, 2024

redeboer commented Jun 4, 2024

shenvitor commented Jun 4, 2024

shenvitor commented Jun 6, 2024 • edited Loading

redeboer commented Jun 6, 2024

shenvitor commented Jun 6, 2024 • edited Loading

shenvitor commented Jun 7, 2024 • edited Loading

redeboer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shenvitor Jun 12, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

redeboer commented Jun 12, 2024

redeboer commented Jun 14, 2024 • edited Loading

This comment has been minimized.

redeboer commented Jun 17, 2024 • edited Loading

redeboer left a comment

Choose a reason for hiding this comment

shenvitor commented Jun 4, 2024 •

edited

Loading

shenvitor commented Jun 4, 2024 •

edited

Loading

shenvitor commented Jun 6, 2024 •

edited

Loading

shenvitor commented Jun 6, 2024 •

edited

Loading

shenvitor commented Jun 7, 2024 •

edited

Loading

shenvitor Jun 12, 2024 •

edited

Loading

redeboer commented Jun 14, 2024 •

edited

Loading

redeboer commented Jun 17, 2024 •

edited

Loading