And it isn't even written in Python!

If/when run into issues with Sphinx, 1st the project should be accessible online then message me with the URL and ask for help. I'm battle hardened; will conquer whatever Sphinx autodoc demons assails you.

This goes for everyone else as well. If have the Sphinx blues, don't whine about it, just ask for help.

Especially if your project is awe inspiring. Online read lots of complaining about writing documentation, but see it as just as important as the code or business model. Your documentation should not suck. Don't half ass it.

Also i'm really curious how autodoc stays broken (for months). Take that to mean, there are things that need to be learned. Not knowing those things Sphinx can be frustrating. For example, dealing with Type aliases and table of contents.

Will checkout your repos. Thanks for comment. It's been a breeze to write python and the docstrings are pretty great. I've had periods where everything just worked for Sphinx autodoc and then others where it's just broken for months. Thanks again

I am glad that PSF is not bowing to these requirements in order to get the grant.

The EU should be stepping in. The entire economic region is dependent on python and even introduced some supply chain security requirements, so this would help resolve those.

For the Makefile and conf.py, it's a Ctrl+P job. tox.ini more Ctrl+P. Crap that goes into pyproject.toml Ctrl+P.

ETA ~20 mins including bathroom breaks and chatting with friends that randomly arrive at the cafe.

Then comes dealing with fixing up the URLs and references. That is the only time consuming bit.

Have posted links to packages i've written, can just go there and five finger discount the configuration files.

Howto autodoc, i'm not licensed to sell without a medical license. But there is a shot for that. ;-)

Would seriously love someone to rip down Sphinxdoc and put this baby to bed.

In my history of using docstrings, I've put maybe 20-40minutes of docs into a 200k+ codebase. It's super easy.

In my history of using Sphinx autodoc, I've spent about 5-10 hours fumbling with Makefiles, configs, and other nightmares and it still has the worst developer experience after about 8 years of using it.

Just spent the last two weeks (no exaggeration) putting documentation together. Ensuring references resolve correctly is the time consuming bit.

extlinks, nitpick_ignore, autodoc_type_aliases, intersphinx_mapping, multiple extensions, and building inventories using sphobjinv, Table of contents using sphinx-external-toc-strict links to both ref and docs.

The table of contents supports both .md and .rst files. With the caveat that the initial file must be index.rst.

Having to relearn all this crap to do the same thing (e.g. mkdocs)? Would rather stick a fork in my eye.

Here is a sample TOC config file wreck _toc.yml from package wreck. Shows globs:, file:, url: links.

This one includes both .rst and .md strict TOC _toc.yml

Output is a user manual web site or a pdf.

markdown and restructuredText are input files, not the end goal.

Sphinx's autodoc tool does gathering documentation and will traverse the whole package with the right config. It can read markdown with myst-parser. It provides HTML, TeX etc as output formats out of the box, however if you need markdown as output you many need an extension.

https://mkdocstrings.github.io/

There are A LOT of these. I have had good experience with https://pypi.org/project/git2md

Says "Support for .gitignore, .globalignore and .mdignore for local projects: Automatically excludes files/directories specified in .gitignore, .globalignore or .mdignore."

If you don't find what you like, I've also found it easy to ask LLMs to just write a tool customized to my use case, usually when I need to somehow condense the code base to make it fit in the context.

Thanks. I didn't know: https://memory-graph.com/#code=x+%3D+%280%2C+%5B1%2C+2%5D%29%0Atry%3A%0A++++x%5B1%5D+%2B%3D+%5B3%5D++%23+calls+list.__iadd__%2C+then+reassigns+x%5B1%5D%0Aexcept+TypeError+as+e%3A%0A++++print%28e%29%0A%0Ax+%2B%3D+%284%2C%29++%23+calls+tuple.__add__%2C+then+reassigns+x%0A%0Aprint%28x%29%0A%0A%0Aclass+MyClass%3A%0A++++%0A++++def+__add__%28self%2C+other%29%3A%0A++++++++print%28%27__add__%27%29%0A++++++++%0A++++%23def+__iadd__%28self%2C+other%29%3A%0A++++%23++++print%28%27__iadd__%27%29%0A%0Aa+%3D+MyClass%28%29%0Ab+%3D+MyClass%28%29%0Aa+%2B%3D+b++%23+calls+__add__+if+__iadd_+doesn%27t+exist%0A&play=

Except if __iadd__ doesn't exist on the type, then __add__ is called. The variable is always reassigned. Quick example:

x = (0, [1, 2])
try:
    x[1] += [3]  # calls list.__iadd__, then reassigns x[1]
except TypeError as e:
    print(e)

x += (4,)  # calls tuple.__add__, then reassigns x

print(x)

What is printed?

__add__ is called with + and __iadd__ is called with +=, and there is a difference: https://www.reddit.com/r/PythonLearning/comments/1nw08wu/right_mental_model_for_python_data/

Yes a you get for free to set the tone, the others are more interesting.

It's always fun to guess whether python will call __add__ or __iadd__.

I so wonder what a will result in.

Good times in 256 vga colors

I once knew how to do this in 68k assembly. Maybe re-learning it in python from this article is exactly what I deserve.

On the sorting logic, not the code itself, maybe calculate differently for each range of total votes?

For example, let's say there are 5 communities with up to 100 total votes, 5 with 1000 and 5 with 10000. You could, for the first, divide the percentage by some constant like let's say 10, the middle one you'd do nothing, and the third one you'd multiply the percentage by the same constant as the first. The resulting number (no longer a percentage) could indicate the engagement.

You want some kind of decay function for when that engagement happened.

The rest is sort of up to you and depends on your math intuition a bit. If you do something like total (votes/10.000)+% relative stuff will weigh heavily until you get close to 10.000 then the votes will dominate no matter how positive the post was. But the 10.000 is arbitrary.

My advice would be to create some fake data that are plausible scenarios, (well liked, low vote), (lots of votes, medium %), (lots of votes, but old) and then you experiment with some functions and curves until you find a mix you like.

If you have multiple values to sort on I suggest using pandas, building a pandas.DataFrame and sort it using the .sort_values() method, which allows you to provide multiple sorting keys. Your data sounds to complex for lists, it is easy to lose the overview. You could work with dictionaries, but then you need to write some ugly loops or comprehension.

Nice one.

Until @fruitcantfly set me straight, couldn't read and understand the version str and was unaware Rust followed a different pattern than Python.