Improving maintainability

[funkyfuture]

i think the code base can improve a lot by employing these tools as formatters and linters:

• black
• flake8
• isort
• mypy
  • while the project is still young, it's advisable to start gradually adopting type annotations rather sooner than too late

[kalekundert]

I'm definitely open to using flake8 and isort, I just haven't taken the time to get them set up.

I'm on the fence about black. There are definitely times when it makes things worse, but the consistency is worth it for projects that get contributions from lots of people. Probably I should get in the habit of using it.

I hate working on projects that use mypy, so even if I thought it would make the code better, I wouldn't use it for my own projects.

---

IMO, the biggest maintainability issue with this project currently is the lack of automated tests. The issue is that I have to implement a system for building self-contained sphinx projects and checking their HTML output, and that seems like a substantial undertaking. But at some point I'll have to bite the bullet and do it.

[haiiliin]

IMO, the biggest maintainability issue with this project currently is the lack of automated tests. The issue is that I have to implement a system for building self-contained sphinx projects and checking their HTML output

You can enable the Build pull requests for this project in readthedocs.

[funkyfuture]

i have to admit that i actually wrote this rather with regards to contributability (accessibility for potential contributors).

I'm on the fence about black. There are definitely times when it makes things worse, but the consistency is worth it for projects that get contributions from lots of people. Probably I should get in the habit of using it.

yes. the rare occassions where it produces something considered as worse are certainly made up by the benefits. getting rid of the habit to manually apply formatting took me some weeks, but then it really increases productivity.

I hate working on projects that use mypy, so even if I thought it would make the code better, I wouldn't use it for my own projects.

not only points it at errors before they occur like flake8, but it also points out questionable design and unconsidered edge cases. that proposal was invoked because of the situation with Section.exclude_section where the docstring mentions a class or an iterable of such, but a None is assigned. a type annotaton would provide a testable documentation for contributors.

IMO, the biggest maintainability issue with this project currently is the lack of automated tests. The issue is that I have to implement a system for building self-contained sphinx projects and checking their HTML output, and that seems like a substantial undertaking. But at some point I'll have to bite the bullet and do it.

maybe it would easier to validate the document tree representations that are then to be passed to the builders?

[bryevdv]

BTW I would strongly advise considering ruff as an alternative to flake8. It is configurable via pyproject.toml (which at this point it seems flake8 will never be), it has very friendly and responsive maintainers, and most importantly, it is written in Rust and is easily 100x faster than flake8 (on the Bokeh codebase ruff is <1s whereas flake8 is 20+ seconds)

[kalekundert]

The project does already use ruff, but I haven't enabled that many of its checks yet.