Suggestion: Make this plugin also work on GitLab repos #9

Open ajhalili2006 opened 4 years ago

It seems that this plugin only works only on GitHub. So, I have some questions:

Is this plugin works on GitLab?
If not, do you have any plans to make it also work for GitLab?

Thanks in advance!

@byrnereese is this package still being maintained? I'd be happy to provide a PR for this.

Currently mkdocs-git-committers-plugin uses the github API, but we could add a more generic local option as well, for example we could use something like:

git log --pretty=format:"%an%x09" <filename> | sort | uniq

I can work on a more elaborate proposal if you're up for collaboration? And afterwards I'd like to contribute support for this plugin to mkdocs-material theme.

Let me know

@timvink I would love the contribution and help. If you want to put together a PR, I would be happy to review and merge it. If it is easier - can you describe how you would implement this? What would the UX/developer experience be like do you think?

Awesome! Will work on the proposal for UX and a first bit of implementation over the weekend.

The technical implementation is fairly straightforward, as we can use page.file.abs_src_path with:

from git import Git
logs = g.log("README.md", n=2, format="%cn %ct %ce").split('\n') 
logs = [x.split(' ') for x in logs]
[{'name': x[0],'datetime': x[1], 'email': x[2]} for x in logs]

# [{'name': 'byrnereese',
#  'datetime': '1556297466',
#  'email': 'byrne@majordojo.com'},
# {'name': 'byrnereese',
# 'datetime': '1552336354',
#  'email': 'byrne@majordojo.com'}]

So the upside of getting committers info from the local git repository is speed, works everywhere and there is no config required. The downside is there is less information available on the user than via the github API (only email and name). And that it makes it harder to write the documentation for both use cases to be very clear for the user while being backwards compatible.

I have a first proposal for the new README.md here. (There's also a start on the technical implementation).

To make the README even simpler, I would suggest to also:

Choose to leave out the last_commit functionality, as you can display the last date with mkdocs-git-revision-date-localized-plugin (disclaimer: I wrote that plugin).
The template code has a lot of JS and CSS attached that I think we could remove. The user is implementing it in his/her theme might want to do it differently. I think the layout should be part of the theme (f.e. I'd like to contribute support to mkdocs-material)

Let me know what you think and I'll work out a clean PR

This is super helpful. Thank you. Generally speaking, I really like the concept. I wish however that there was a much better way to marry the two methodologies together.

For example, could we rearchitect the plugin so that the commit history is pulled locally? But then userpics and other metadata can be loaded by a separate plugin. It might reduce the API load and traffic.

One plugin generates a commit history.
Another plugin can either load GitHub userpics, or another plugin might render gravatar userpics based on email.

Of course, I am just thinking out loud.

I wish we could get access to a first and last name. Then you could generate userpics purely through CSS using the committer's initials.

The last requirement is that it must work on readthedocs.org. I wonder if commit history is available when it conducts its build process. I assume yet, but we should make sure.

As for CSS and HTML - I am happy to NOT ship that with the plugin. I think though we should make recipes readily available for theming and styling commit histories.

This is super helpful. Thank you. Generally speaking, I really like the concept. I wish however that there was a much better way to marry the two methodologies together.

Good to brainstorm together :)

We need to clearly separate concerns; a mkdocs plugin should provide raw information, a mkdocs theme the fancy presentation.

If we support both github api & local git sources, it would mean we provide two distinct sets of information. In turn, the theming is very different, if only because you can use avatars and github users name when you use the github API. So I agree it's better to separate out into two separate, dedicated plugins.

As an aside, you asked about commit history when deploying using readthedocs. There is no need to pull anything locally, because the commit history is already local. When you clone a repo the info is stored in a hidden folder called .git. Same for readthedocs deployment btw, they clone a repository URL and then run mkdocs build inside it (see their how we build documentation).

So now the challenge is how these two 'twin' plugins work together. You mention one plugin could use the other to reduce API load. I think one plugin depending on another would makes things unnecessarily complex & introduce possibilities for hard-to-debug errors.

My suggestion: I write a new plugin that focusses only on providing information on page committers from the local git repository. In both plugin's README we make sure to use a similar structure, clearly explain the usecase and link to the other twin plugin. That way users can decide what they want to use: rich info from github using the API, or basic info from the local git repo.

Then there's the issue of clear naming. Ideally mkdocs-git-committers-plugin would be renamed to mkdocs-github-committers-plugin to make the use-case clearer, but the name change is probably more confusing for users. To make a clear distinction, the new plugin could be called mkdocs-git-authors-plugin.. as it only retrieves git username and email.

Any thoughts?

I do think we can help promote each other's plugin by educating our users about our respective use cases, and choosing greater naming clarity.

But I thought the initial intent was to try and merge the common functionality between these two plugins/ideas - to produce on building a single plugin on which could both collaborate.

Let's approach this problem this way: my goal is simple, to display a list of committer's userpics on each of my pages. The question is: what is the best way to achieve that.

My approach is a little brittle to be honest. It requires people to point to a specific repository and branch. Your approach is a huge improvement in that it simplifies setup. Commit history is inherent to the local filesystem - users do not need to point at a github repository in their config. It is inferred. I love that.

Your solution also makes generating a list of contributors A LOT faster. That too is great.

One plugin could do just that - provide a looping construct to let designers display a list of committers. I would use that plugin if it existed...

But I also want to show a userpic, preferably from their github profile. If the local commit history could get me the person's github username, then another much simpler plugin could just fetch a user's github profile data and add it to the template context. Is that possible do you think? Does that sound like a good architeture?

Yeah good points, and yes my preferred options is still to do everything in one plug-in if possible..

I understand your point now on getting the usernames from local commit history, and then giving users the option of enabling the GitHub API to retrieve the userpics.

However, if we start from a local commit, we only have name and email. The name is no good, because even in a commit from a GitHub user the name can easily be different from a github username (in my case 'Tim Vink' vs 'timvink'). email is better as a unique ID, but when I look at the github commit API I see no way to match email with a github username, which in turn we can use to get the userpic. Maybe I'm missing something?

I think your current approach is the best way to achieve the goal: displaying a list of committer's userpics on each of the pages. I don't see the possibility to speed up / reduce API rate by using local commit history.

So, I think the conclusion is that the cleanest way is two plugins doing to separate things, and making users choose what they want: at a bottom of a page a simple text with committers, e.g. "Written by: byrnereese, Tim Vink", or a nice overview of github userpics.

I'll get started on the implementation of a plugin here (without naming or publishing yet), because we can re-use the code even if we crack the nut on how to make it a single plugin.

In @timvink's first reply, let me think if I can write (or rewrite) some Python code. Maybe we can use Gravatar, but there's only one issue: if an email address doesn't have associated with a Gravatar, we need to use the default option or pull from GitHub/GitLab APIs.

In his another comment, renaming mkdocs-git-commiters-plugins to mkdocs-github-committers-plugin is a good decision for user cases who host their docs on GitHub while creating an new plugin called mkdocs-git-authors-plugin for different user cases between Git hosting services (and maybe including CI/CD services).

@AndreiJirohHaliliDev2006 I like the idea of adding gravatar!

I built a first version of mkdocs-git-authors-plugin: https://github.com/timvink/mkdocs-git-authors-plugin

Let me know if you have any feedback. ~~Not yet released to PyPi, I want to write some more unit tests first.~~ Released on PyPi.

byrnereese / mkdocs-git-committers-plugin

Suggestion: Make this plugin also work on GitLab repos #9