Documentation excellence

[JuroOravec]

This issue is to track improvements for the documentation site, as originally written up by @GabDug in #420.

Preview at https://EmilStenstrom.github.io/django-components/dev/

Tasks

• CI to generate on release (tag and latest versions)
• CI to generate the dev version
• CI to generate the documentation on PRs/branches
• API Reference should not have empty pages
• Review and revamp the documentation
• Fix links in documentation, and add links to API reference.
• Cleanup the plugins and extensions
• Cleanup the configuration
• Review header levels in the documentation
• Documentation on hatch
• Update CI to remove testing mode (all the XXX)
  • CI should be disabled on forks
• Update CI to enable strict mode
• Fix the Github README
  • Should present quickly and redirect to the documentation for more information
  • Links should be to latest/dev doc
• Fix the Pypi README
  • Pypi README can be generated on the fly (with hatch-fancy-pypi-readme for instance)
  • Can have more information than the Github README, but should still redirect to the documentation for more
  • Link should be to the released version (not latest/dev)

Nice to have

• Logo
• Favicon?
• Choose a color scheme, or create a custom one?
• Inline examples are included automatically from tests or the example project
• Add mkdocsstrings references where appropriate (in code and in docs)
• Contributors page?
• Proper "added in version x.x" macro?

[mlissner]

I'm evaluating this package for use in an old website that we're upgrading, and a contributors page would be helpful. Something I'm trying to figure out -- probably my top priority -- is how popular this project is, and whether it will be around for the long haul. This is a hard thing to measure, but one proxy for it is contributors. I imagine this is a particularly important thing for this project because, unlike others, it's more likely to be used by larger more established websites (which are more likely to have component libraries).

One other thought is that it'd be neat if the documentation was itself developed using Django components. Probably too late for this idea, but it might be a nice if the docs were an example to look at.

Thank you!

[EmilStenstrom]

@mlissner Hi Mike! Happy to hear that you are considering using this lib.

One thing that many forget is that a company like yours (I’m assuming it’s a profitable one) have a big say in if this is works out in the long haul or not. It’s as simple as contributing $100-300 per month for as long as you use the library. This ensures there will always be people around that helps maintain and develop the library.

It’s currently me and Juro that maintains it, with Juro doing pretty much all the work part-time, for well under a reasonable salary.

[JuroOravec]

@EmilStenstrom Great point. To give an idea to others, currently the contributions cover roughly 3 hrs/months, but I put in ~30 hrs weekly. So definitely not sustainable financially nor otherwise (I have another 20 hr/wk part-time job beside this project to pay the bills).

Btw @mlissner could you give examples of projects which you think do it well to convey the message of how popular they are? Or the ones that make you feel that the community is active?

One other thought is that it'd be neat if the documentation was itself developed using Django components. Probably too late for this idea, but it might be a nice if the docs were an example to look at.

There was the idea for this, but then we went with mkdocs. Yes, it would be cool to use django-components for documentation, but mkdocs offers so much more, and so much faster.

But to try to dissect the comment, @mlissner, is it that you would want to see an example of a mid/large project that uses django-components?

[mlissner]

Thanks for the push here. Our organization does a lot of open source too and we're definitely familiar with the challenges. We've been at it for a long time now though, and it's true that we're at a point where we should start contributing more than code. It's been on my mind.

could you give examples of projects which you think do it well to convey the message of how popular they are? Or the ones that make you feel that the community is active?

I don't know off the top of my head, but what I'm looking for is some kind of "social proof." I think for projects like this, that means either well-known folks in the Django world or major sites that have adopted it. Like, I remember learning years ago that Instagram used Celery, and whenever I see a Django fellow talking about or using something, that's usually a major vote of confidence?

I hope this is helpful. Our site gets about 40k visitors/day, so if we go with this library, we'll certainly be happy to put our name and a quote somewhere.

[JuroOravec]

@mlissner Thanks for explaing that!

Yeah, I'd be great to have social proof, but, well, it has to start somewhere. Don't know about @EmilStenstrom, but at least I haven't yet asked users share their stories, so don't know who's our users.

But for now, the best social validation I can offer is:

• django-components is being used for internal tools at Dcode - tiny userbase, mid-sized project (~80 components) - This is where I work
• Other than that, before I went freelance, I worked at BenevolenAI for 2 years in a web dev team that included, among other, senior engineers from Google, Deloitte, and Citi. So I had good teachers 😄

Btw, @mlissner, if you want, ping me on [email protected] and I could give you an anonymous tour of my project. I'd be also interested to see how you guys manage stuff, if possible, since I'm still relatively new to the Django ecosystem.

[mlissner]

Love it. Let me take a rain check on the tour, since we're still evaluating and I don't want to take any (more) of your valuable time, but you can see our code here, if you want (it's big): https://github.com/freelawproject/courtlistener/