Starter pack: Show contributors

canonical / open-documentation-academy

Learn open-source software documentation skills with Canonical

https://canonical.com/documentation/open-documentation-academy

Apache License 2.0

69 stars 39 forks source link

Starter pack: Show contributors #18

Closed ru-fu closed 5 months ago

ru-fu commented 7 months ago

GitHub repo: https://github.com/canonical/sphinx-docs-starter-pack

See https://github.com/canonical/sphinx-docs-starter-pack/issues/155.

We would like to include information about the contributors to a specific documentation page in our template. This information is available from GitHub - we can extract the number of contributors and their GitHub accounts from the history of each file.

The information will then need to be processed and included in our Sphinx template (for example, in the footer).

Note: This is a programming task rather than a documentation task. It requires Python skills and some familiarity (or willingness to learn) with Sphinx, Jinja, and GitHub APIs.

Unique-Usman commented 7 months ago

Hello @ru-fu I will like to work on this issue. Can I be assigned to it. Thank you very much.

ru-fu commented 7 months ago

@Unique-Usman Sure, great you're interested in that task!

There's some more information in the linked issue. Overall, the steps will probably be:

Find out how to retrieve a list of contributors for a GitHub file.
Determine where in the output the information should be displayed (for example, it could be at the top of each page as suggested in the original issue, or maybe it would work better in the footer or somewhere in the side bar?).
Update the Sphinx template to actually include the contributor list.

I think this will be a very interesting (and challenging :slightly_smiling_face: ) task, and I'm really looking forward to what you come up with! Get in touch if you need any pointers or if there's anything we can help with to get you started.

Unique-Usman commented 7 months ago

thanks @ru-fu I will look at it and get back for any help.

Unique-Usman commented 7 months ago

@ru-fu I checked it out. My question is

The page we want to get the contribute list for is -> https://github.com/canonical/sphinx-docs-starter-pack ?

And it will be show on this page right

ru-fu commented 7 months ago

@Unique-Usman Yes, this is one of the pages. We'd like it for all pages in the documentation, however.

So we'd want to display the contributors to this GitHub file on this page, as you said. But we also want to display the contributors to this GitHub file on this page.

In the Sphinx template, you can actually access the file name of the file that is being processed. You can see an example for how to access the corresponding GitHub file here: https://github.com/canonical/sphinx-docs-starter-pack/blob/cb36129c16a6cf3e1a7962b78e4971e33bd6cd8a/.sphinx/_templates/footer.html#L98

ru-fu commented 5 months ago

Fixed in https://github.com/canonical/sphinx-docs-starter-pack/pull/203

Thanks a lot! :rocket: