Improve ability to automatically compile documentation on more architectures and configurations. #398
Conversation
|
After a lot of trial and error, I discovered that the username passed to the Keypair constructor must match the username used in the SSH URL, rather than whatever username was used to create the public key. I strongly suggest the documentation is updated to indicate that, and to indicate that it is indeed paths to the keyfiles that must be passed. |
The username specified in the URL is a hint for the credentials callback (which it could use to prefill a user prompt). What we use is only ever the username that you provide in the
There is no such concept for SSH keys. The keys are associated to a particular user by the server following its own rules. The username when using ssh to perform Git operations against GitHub and many other hosters is |
|
There is bound to be some improvements/clarifications we can make to the documentation to say more explicitly that we use whatever is passed, as it's written from the point of someone who knows how the library behaves. But I don't think this is the case for hoster-specific hints. |
|
I've tried making some changes to the docblocks within the code and running 'make html' to view the changes locally. However, none of the changes I'm making seem to take any effect. I'm obviously missing something; I get the feeling that sphinx is looking at the version installed with my package manager rather than the copy I have checked out locally (and am running the commands within). Are you able to point me in the right direction? |
|
Because pygit2 is partly in C, it involves two steps, and sphinx looks at where that gets built. You need to run |
|
I'm a newcomer to writing documentation in sphinx, so please excuse my ignorance, but shouldn't that be documented somewhere? What exactly will the result of running 'setup.py build' be? What files will be copied where? Will it affect the version of pygit2 installed with my package manager? |
|
Also, why am I able to compile the documentation successfully if I haven't run that command? |
|
Yeah, whatever it is that's compiling the documentation is looking in |
|
Upon even further inspection, it would appear that the sphinx conf.py file assumes 64-bit python2.7 has been used to run |
…inx docs This almost certainly isn't perfect, but it's a big step up and should work on (at least) any 32-bit or 64-bit version of python2 or python3 running on Linux (rather than just 64-bit python2.7 on Linux).
Includes a couple of small grammar fixes to other docstrings.
djmattyg007
changed the title
|
I've converted this to a pull request, and have updated the subject of the issue to match. The pull request aims to make it easier to compile the documentation automatically without needing to alter the sphinx conf.py file. It also updates some documentation relevant to issues discussed previously in this thread with the hope of making it easier to understand. |
| @@ -61,6 +61,11 @@ class Keypair(object): | |||
| This is an object suitable for passing to a remote's credentials | |||
| callback and for returning from said callback. | |||
|
|
|||
| :param str username: the username used in the remote URL | |||
There was a problem hiding this comment.
Again, this has nothing to do with the username the user may have passed as a hint. This username is the only one that counts, and it has to be the username as which you wish to authenticate to the ssh host.
|
I've pushed another commit that hopefully clarifies the point in your previous message. |
I've spent almost an hour trying to find out what format I should pass the public and private keys in as when using the Keypair class. To me, I would just pass in the path to my private and public keys like so:
Unfortunately, when I try and run that code, I get this error:
Am I supposed to read the keys into memory myself from those files and pass those to the Keypair constructor? Am I just getting the username wrong? I can't tell, and the documentation doesn't give any information about this.