You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An issue I found while contributing to the Sphinx extension, coupled with the lack of a CONTRIBUTING.md document (which is another, unrelated issue) is that it was a bit difficult to navigate what was going on for someone whose Sphinx skills have been a bit rusty since quite some time. I would like to put in a request to refactor the codebase and move things around, and here are my suggestions:
Proposed Solution
A complete refactor might take a lot of time and hinder development efforts, but at least moving the IFrame classes to a non-namespace sub-module jupyterlite_sphinx/iframes/ and then similarly moving the directives to jupyterlite_sphinx/directives/ can work
Another level of hierarchy exists with the Directive classes, where all of them are subclasses that derive from _LiteDirective, which itself derives from the standard SphinxDirective. These would be likely candidates to split up into multiple files, and it should be easy to fix up their imports back into jupyterlite_sphinx.py (it might make sense to rename the file because of the folder structure, i.e., jupyterlite_sphinx.main sounds a bit better than jupyterlite_sphinx.jupyterlite_sphinx)
Besides that, I'm not sure if anything else can be extracted out of a refactoring process (the jupyterlite_sphinx.js and jupyterlite_sphinx.css files are standalone in their usage and exist only for copying into the _static folder for a documentation website.
Additional context
Though it is a bit outdated and unmaintained at the time of writing, another project: https://github.com/sphinx-contrib/cookiecutter has a nice structure to offer. However, it may or may not be needed here for now because the packaging is modern with hatch anyway and a test suite does not exist (and that may not be required anytime soon?).
Thanks @agriyakhetarpal, but I don't really have an opinion on this one way or the other, beyond that I agree it would be good to add a CONTRIBUTING.md. I had no experience working on sphinx extensions prior to this and just fit the try_examples directive into the existing project structure. If you want to work on this, I think this should be decided by the other maintainers.
Sure! My suggestion here is quite trivial, really, so I'll be happy to start my work on this once some of the recent PRs can get merged – and maybe after we come out with a release with those, to not cause any trouble(s) before a release.
Problem
An issue I found while contributing to the Sphinx extension, coupled with the lack of a
CONTRIBUTING.md
document (which is another, unrelated issue) is that it was a bit difficult to navigate what was going on for someone whose Sphinx skills have been a bit rusty since quite some time. I would like to put in a request to refactor the codebase and move things around, and here are my suggestions:Proposed Solution
IFrame
classes to a non-namespace sub-modulejupyterlite_sphinx/iframes/
and then similarly moving the directives tojupyterlite_sphinx/directives/
can workDirective
classes, where all of them are subclasses that derive from_LiteDirective
, which itself derives from the standardSphinxDirective
. These would be likely candidates to split up into multiple files, and it should be easy to fix up their imports back intojupyterlite_sphinx.py
(it might make sense to rename the file because of the folder structure, i.e.,jupyterlite_sphinx.main
sounds a bit better thanjupyterlite_sphinx.jupyterlite_sphinx
)jupyterlite_sphinx.js
andjupyterlite_sphinx.css
files are standalone in their usage and exist only for copying into the_static
folder for a documentation website.Additional context
Though it is a bit outdated and unmaintained at the time of writing, another project: https://github.com/sphinx-contrib/cookiecutter has a nice structure to offer. However, it may or may not be needed here for now because the packaging is modern with
hatch
anyway and a test suite does not exist (and that may not be required anytime soon?).cc: @steppi
The text was updated successfully, but these errors were encountered: