Question on background of jinja-everything and remove docstrings in scripts

[laenan8466]

Hey @pawamoy ,
I was working on a project and noticed, that you did some refactoring:

• Write comments, not docstrings in internal modules/scripts (bedf879).
• chore: Add jinja extension to all files (d5fb390)

I'm curious, why you decided to use comments, not docstrings. Is it to prevent these functions showing up in the API documentation?

Also I'm curious, why adding a jinja extension to everything, even if nothing is changed? Is this for easier usage with formatting? Prevent checking on that files?

Priority: low, just curious. :-)

Cheers,
Laenan

[pawamoy]

Hey @laenan8466, thanks for your questions!

Docstrings vs. comments

I recently started using an "internal" API layout (see fd500cc):

project/
  src/
    package/
      _internal/
        *.py
      __init__.py  # everything exposed here

Some reasoning on using this layout: https://mkdocstrings.github.io/griffe/guide/users/recommendations/public-apis/#module-layout.

So, now that most modules are internal (private), I enforce that they do not have a docstring, because docstring are meant for users, and users aren't supposed to import from these private modules. Instead, these modules now use comments, because comments are reserved for contributors/maintainers: people working on the code. I hope that makes sense?

Jinja extension

I played with REUSE in the reuse-spdx branch, and to allow the user-selected license to show up in every file, I had to make them all Jinja templates. In the end, I decided not to move forward with REUSE (it posed a few DX challenges), but I kept the change that added the .jinja extension to all files. The advantage is that I don't have to think about whether a file should have the suffix or not, and this prevents a mistake I made several times in the past: adding some templating to a file but forgetting to add the suffix. It has an inconvenient too: it probably makes rendering of the template a tiny bit slower, but this is far from critical IMO.

---

I'm curious: do you use the template, or do you maintain your own fork maybe? 🙂

[laenan8466]

Hey!

Docstrings vs. comments

Totally makes sense. I often use the documentation as tool for developers/maintainers, to understand quickly how a tool works and where one could have an angle of attack for changes/features/...

I guess the big difference here is, that I do mostly applications, and not libraries. And while applications also follow the src-layout, they differ in some points from structure of docs/etc.

Jinja Extensions.

Got it! :-) Was there, done that. Have you found a good solution for linting/formatting of *.jinja files? I normally try out s.th. new in a project with the template and then copying them to the template and replacing project specific parts with jinja-calls.

---

Your template was 'too much' for me to start, so I build a template on my own, only adding step by step some features. It is not at all on par with yours. Long run goal is to use just your template for all private projects.

[pawamoy]

linting/formatting of *.jinja files?

Nope, never found a solution I was satisfied with. Handling of multiline tags is pretty poor in each of them. I guess the community lacks a sanctified style guide.

Your template was 'too much' for me to start

Completely understandable. I did the same back in the days when I learned many, many things by forking the Cookiecutter template for Python from ionelmc and "making it my own".