Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/miohtama/sphinxcontrib.contributors

Show document contributors on the page
https://github.com/miohtama/sphinxcontrib.contributors

Last synced: 2 months ago
JSON representation

Show document contributors on the page

Awesome Lists containing this project

README 

        
.. contents::



Introduction

============



`Sphinx `_ is a software development documentation tool

written in `Python `_. It is used by

hundreds of projects, of some of which you can find on

`readthedocs.org `_.



``sphinxcontrib.contributors`` Sphinx extension adds a sidebar box showing

the contributors of the documentation. This information is sourced from Git commits

and Github user profiles.



.. image:: https://raw.github.com/miohtama/sphinxcontrib.contributors/master/docs/screenshot.png

    :width: 200



Often writing open source software documentation is a thankless task.

Providing documentation is oversighted by many software developers.

People who write documentation do not get to be in limelight like rockstar developers do.

The ``sphinxcontrib.contributors`` Sphinx extension

encourages writing documentation by giving the

face time and link love for the writers

on the documentation page itself by adding a

new box to Sphinx sidebar.



Benefits



* Give the credit where the credit is due



* The process is automatic based on git history

  and there is no need to have separate contributors list



* Show that the documentation is written by humans and it doesn't born automatically



* Encourage people to write more documentation



Examples

=========



See `Plone Developer Documentation `_.



Installation

==============



Install the package to your virtualenv:



    pip install sphinxcontrib.contributors



Install templates and static media files needed for  this extension to work.

`You can download the files from here `_.

Use Github raw file view to download the file.



Add to your Sphinx **static** resource folder the following files::



    transparency.min.js

    contributors.js

    contributors.css



Add to your Sphinx **templates** folder the following files::



    contributors.html



Usage

=======



The Sphinx HTML is fitted with information of Github API URL where to get commit for a specific file.

Then a JavaScript AJAX request is used to pull the commit information. The authors are parsed from the commits.



You get a Github username as tooltip, Github profile link and Github avatar of each author.



* If there is Github username available, then the Github gravatar or identifcon is displayed with a

  link to Github profile page



* If the commiter was not a Github author, then the committer's name is displayed on a blank

  image



Limitations

=============



Currently the authors are resolved on the client-side using Github public API.

This is suitable for low traffic documentation hosting.



* Resolving authors during the documentation build time increases the build time considerably



* With large documentation builds you might hit Github API throttling threshold,

  making it difficult to do continuous documentation builds



Source code and issue tracking

================================



`See the project on Github `_.



Other

=========



The extension uses ``git`` command and Python `sh library `_ to extract the Git repository information.

`Transparency client-side semantic templating library `_ is used to generate DOM tree for face links from Github API JSON.



This project was created in the `Plone `_ `Conference 2013 `_

with awesome people, many caipirinhas and a lot of fun.



Author

==========



Mikko Ohtamaa (`blog `_, `Facebook `_, `Twitter `_, `Google+ `_)