Document how to work on this project

[pradyunsg]

Is your feature request related to a problem? Please describe.

It is currently unclear to me (someone new to the project!) what I should do to work on this theme, and what workflows are for the various tasks related to the project.

A link to the documentation page where you see an issue.

N/A

Describe the solution you'd like

A clear "Development/Getting Started" guide (like https://pip.pypa.io/en/latest/development/getting-started/) that describes how to setup a development environment, and how to do common development workflow tasks -- namely running the code, generating the documentation, running linters, running the tests.

I suggest using something like nox, to simplify the workflow tasks even further, to be "run nox -s <name>". Being able to do nox -s lint / nox -s docs / nox -s tests and having it manage setting up the environments, would be great. Once I figure out what the setups look like, I'd be happy to file a PR adding a nox configuration for this project, if it would be welcome. :)

[pradyunsg]

Suggestion: Having something like nox -s docs-live, that uses sphinx-autobuild to regenerate the documentation on changes to the HTML, with any additional compilation jobs also spawned in the background. Again, I'd be happy to include this in the aforementioned PR, if it would be welcome. :)

What I did on a different sphinx theme that I was working on: https://github.com/pradyunsg/materialism/blob/39590acf83e97b825da619ec1aca0336ccd8297f/noxfile.py#L55

[pradyunsg]

sigh

Looks like I can't use sphinx-autobuild with this theme as-is, since it recompiles the scss file immediately upon importing conf.py -- which results in the theme constantly getting reloaded on the browser since the folder it is watching gets modified. Sphinx also doesn't detect that the css file has been changed, and does not copy it over to the build directory which means that the page does reload but loads the same assets as before, even though the .css file in the source directory has changed. >.<

I'm gonna step away for today now. I've already made a lot of noise in this repository, and this feels like a workflow clash so I'll wait until I get some inputs on how others iterate on the HTML/CSS for this project before trying again. :)

[choldgraf]

@pradyunsg I will write up more content in the contributing guide today (https://sphinx-book-theme.readthedocs.io/en/latest/contributing.html but right now it is very sparse).

Could you explain more your sphinx-autobuild process to me? I suspect that you are more advanced at Sphinx than I am 😅. The SCSS -> compilation is not particularly sophisticated here, I'm just building it from within the setup(app) but I am open to better ways of doing this.

[chrisjsewell]

I will write up more content in the contributing guide today

Make sure this is integrated with https://github.com/executablebooks/.github/blob/master/CONTRIBUTING.md (@pradyunsg have you looked at this?)
The CONTRIBUTING.md should be removed from this repo, or it should at least link to the central one, since currently it is "overriding" it

[choldgraf]

yeah I agree - this is just a carry-over from before that file existed and we haven't updated it. I'll plan to update that contributing file so that it links to the EBP one, and also adds sections that are SBT-specific.

Alternatively I could add a little script to automatically pull the latest CONTRIBUTING.md when the site is built and insert it directly into the docs. I am curious what you think about that approach (it's what we are using on the EBP website)

[pradyunsg]

Could you explain more your sphinx-autobuild process to me?

There isn't much really. IMO sphinx-autobuild is a really useful tool for when you're working on themes/documentation and don't want to constantly jump between 3 apps (browser, editor, terminal).

Change sphinx-build <whatever> to sphinx-autobuild <whatever> and it gives you a development server on localhost:8000 with "LiveReload" (i.e. if the generated files change, the browser reloads automagically). Change and save a file, and it'll trigger a rebuild, and refresh your browser page.

The issue with this project is that building it regenerates the file, which triggers a rebuild, which regenerates the file, which triggers a rebuild... you get it. :)

(@pradyunsg have you looked at this?)

No! Otherwise I would've jumped at the chance, given the license to use emoji in commit messages! >.<

[pradyunsg]

I am open to better ways of doing this.

IMO the easiest way might be to decouple "build with the theme" from "compile the scss files" and perform the compilation elsewhere. Depending on how you want to do things, we could commit the generated css file, or have it get built when generating the sdist/wheel.

That'll also let us use compilers for scss that have a CLI + additional features (like auto-rebuild). We can also separate the source "scss" from the destination -- i.e. not have *.scss end up in the built site's _static. I like https://github.com/sveetch/boussole (since it's "just" Python-with-libsass) so if you're open to it, I'm happy to switch us over to such a mechanism.

Note to self about what a noxfile could look like

• nox -s lint: install and run pre-commit.
• nox -s docs: install documentation dependencies, and run sphinx-build.
• nox -s docs-live: install documentation dependencies + sphinx-autobuild + boussole, run boussole watch and sphinx-autobuild.
• nox -s tests: install test dependencies, run pytest.

[chrisjsewell]

IMO the easiest way might be to decouple "build with the theme" from "compile the scss files" and perform the compilation elsewhere.

I agree that a live build is desirable; essentially replicating the common workflow for working with JS/HTML/CSS projects using webpack/parceljs. But the SCSS compilation should be integrated, as it is for these two tools.

I'd note that sphinx-autobuild is essentially a dead project, having received its last commit 3 years ago (with unanswered issues/PRs since then). I would suggest forking it into this org and implementing sphinx-doc/sphinx-autobuild#70, which should allow for built-in scss compilation.
(or easier just make a new (clone) package, since its only a few 100 lines of code)

[choldgraf]

Maybe we could just add the SCSS compilation as a pre-commit script rather than a part of the build process? E.g. it'd fail if the compiled CSS was different than the last-committed CSS? Then you disentangle "compile when the docs are built" vs. "compile first, then build docs w/ static assets".

I'm always a bit worried about adding more webdev-specific infrastructure because it is another barrier for people who aren't familiar with it (e.g. webpack, yarn, etc). I feel similarly to nox - it's a question of "how useful is this to the developer workflow" weighed against "how confused will newcomers be using this if they haven't heard of it before"...but open to a discussion if that is the best option.

[pradyunsg]

Nox is a much lower barrier to entry IMO, given that it's pure Python and even the configuration is pure Python.

[choldgraf]

I gave a stab at this in #163 but we can definitely continue to iterate here.

@pradyunsg wanna write up a short brief on what nox is and how it works? Then we can decide if it's a good idea (vs something like make etc?) and can also use your brief description as a starter for the developer docs if we use it.

[pradyunsg]

Sound like a plan, for something I'll do in the weekend.