Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation improvements for Blob.diff and Blob.diff_to_buffer #378

Merged
merged 2 commits into from
Jun 27, 2014
Merged

Documentation improvements for Blob.diff and Blob.diff_to_buffer #378

merged 2 commits into from
Jun 27, 2014

Conversation

michaeljones
Copy link
Contributor

I noticed the documentation not rendering properly for these methods. The first commit should fix this and the second attempts to improve the formatting using the parameter lists that Sphinx supports, which have already been used for pygit2.clone_repository.

I have specified the return type with rtype but perhaps this is redundant as it is shown at the end of the signature.

I also don't really know what to list as the type for the GIT_DIFF_* flags.

I hope it helps,
Michael

They were both missing a closing parenthesis which stop Sphinx from
interpreting and formatting them properly.
We switch to a parameter list for both functions and add a return type.
We also remove the indentation from the second line of the explanation
which was causing Sphinx to return it as two lines instead of one
continuous one.

We also added return types.

I am not sure of the type of the GIT_DIFF* flags so I have not included
that.
@jdavid jdavid merged commit b96b285 into libgit2:master Jun 27, 2014
@jdavid
Copy link
Member

jdavid commented Jun 27, 2014

The problem using ReST/Sphinx in the doc-strings is it looks ugly on pydoc and the interpreter:

>>> help(...)

The solution used in Python is to double the documentation: the doc-strings, plus a separate tree for the Sphinx documentation not re-using the doc-strings. But we cannot afford that much work, so we have to choose.

@michaeljones
Copy link
Contributor Author

Hi,

You make a really good point. I'm not sure the official Python docs use the :param: mark up at all. Maybe we should revert the second commit and go back to the original format. I can't see much gained from using the :param: stuff, I just thought it was the 'official' way.

I don't really like the pink/purple default colouring either. I'd be happy to revert those and convert the clone_repository docs if you'd like?

Cheers,
Michael

@jdavid
Copy link
Member

jdavid commented Jul 22, 2014

Just opened a new issue #393 for this. And just one commit 5d01300 to test the waters.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants