Separate repos for pydoc-markdown 4.6+ and 4.5.1

[mcarans]

pydoc-markdown 4.6 was a significant change to 4.5.1 involving a new approach to making documentation. It has left users like me in limbo as the new approach is much more complicated than the old for the simple description page + API docs setup that I have but the old approach is now deprecated, its documentation is removed and it will be dropped in future according to the README:

The old style of using Pydoc-Markdown with a YAML or PyProject configuration to generate files and kick off the build is now deprecated but will be maintained for the foreseeable future (at least until the next major version bump). It is strongly recommended to migrate your existing projects to using the Novella build backend.

There is a discussion about how to replicate an old style setup in Novella, but that seems to have stalled. From GitHub, there have been no new commits for a few months whereas looking back at previous versions, there was much more activity. This has led me to wonder if I need to look for an alternative to pydoc-markdown.

I would like to suggest that 4.5.1 (and earlier) be in a separate repository to 4.6+ with documentation restored (or alternatively undeprecating the old style and adding its documentation back alongside the 4.6 docs). This way support for the old style can continue rather than it petering out. If you don't want to maintain the old style, then at least there would be the option for a new maintainer to take over. If you can maintain it, then I'm sure there will be many happy users.

[NiklasRosenstein]

Hey @mcarans , sorry for the late response. Unfortunately I don't find a lot of time at the moment to maintain pydoc-markdown.

I hear you, and the rest of the community. I thought that the new approach was in all ways superior, but I was wrong about the adoption. It seems that either people can't be bothered to look at the new way, which is fine. It can mean a rather large architectural shift in how they build their docs. Or how they're generating their docs is not compatible with the new method.

I think I would prefer if if we just "un-deprecate" the YAML/TOML style configuration, and we support both modes (and it's ok if there's a feature disparity between them, if the docs point out exactly the capabilities of each).

What do you think?

[mcarans]

That would be great - it is a relief that the YAML/TOML version will continue to be developed and will be a first class component rather than deprecated. I look forward to seeing the status change reflected in the documentation. Thanks @NiklasRosenstein !

[mcarans]

I've created an issue for this: #286