Find mechanism to help generate docs and changelog

[JAS-lzn]

Find some mechanism (perhaps a decorator?) to help generate information/metadata that could be used to generate docs and changelog info

Said mechanism should be able to generate tags like what the Marlin docs have and allow us to set up a warning when doing a release to force the dev to document some feature/method in the changelog

[jmlopez-rod]

Here is an idea. Since this can be computationally expensive we could create a script that outputs a json object with the versions when a module, class, attributes, functions, parameters where first introduced. If we have this data then we can write a mkdocs plugin that incorporates it into the docs. Here is a first attempt:

http://literatejava.com/git/how-to-find-the-git-commit-introducing-a-given-change-into-a-file/

$ git log --source -S 'def tag_release(' -- packages/python/m/git.py
commit 0c9bf53897e8d096f341d134e01ff9e3c508bef4 HEAD
Author: Manuel Lopez <jmlopez.rod@gmail.com>
Date:   Tue Sep 12 23:07:45 2023 -0500

    git tags (#104)

    * add git commands to manage tags

    * add tag_release

    * add changelog summary

    * keep track of major and minor versions

By searching for the first commit where a string is introduced we can then try to find the first version tag that appears after the commit.

We could use regex to find out when a parameter for a function was first introduced as well. In this way now projects do not have to add any decorators, instead we rely on git to let us know the git tag when something becomes accessible. In the case that there is no tag then we write the default branch or point to the changelog unreleased section.

mkdocs-material has a nice tag they use to label it:

https://squidfunk.github.io/mkdocs-material/conventions/#version