[Twisted-Python] Distributing apilinks.py
Hi,
Right now apilinks.py is located in Twisted at docs/_extensions/apilinks.py, but a copy can also be found in pydoctor project.
While reporting a bug for apilinks.py in Twisted I was ask to send the patch upstream in pydoctor [1]
During the review of the patch in pydoctor, pydoctor's maintainer agreed that there should be a single copy of this file but don't know what's involved in achieving that. [2]
Can someone involved in using apilinks.py in Twisted provide some feedback regarding distribution of apilinks.py file?
Many thanks!
[1] https://twistedmatrix.com/trac/ticket/6954 [2] https://code.launchpad.net/~adiroiban/pydoctor/1282458-apilinks-anchor/+merg...
Eventually, apilinks should just go away. I think I have convinced Michael (pydoctor's maintainer) that pydoctor should just genereate an objects.inv that sphinx can read. Then the regular :py:*: annoations can be used, rather than the apilinks ones (which interpert <> backwards anyway).
That doesn't address the issue of what to do in the mean time. Looking at the code, it looks very similar to what the builtin extlinks extension does; except that apilinks wants `path.to.object <title> and extlinks wants `title <path.to.object>`. (But I guess this doesn't address the issue of # in the links being put in the wrong place. But, https://twistedmatrix.com/documents/current/api/twisted.web.iweb.IRequest.ge... does exists (probably to make this kind of linking work.
Tom
Hi Tom,
Many, many thanks for pushing this forward!
IRequest.getSession.html and extlinks is a workaround, but I hope that we can fix the source problem soon so that we don't have to stick with the workaround for to long.
Is there a ticket in pydoctor for the generation of objects.inv ?
Michael, are you convinced that it would be nice for pydoctor to generate objects.inv ?
I think that implementing this feature could help other project using only sphinx for both narrative and api documentation. I can try to send a patch for that.
Thanks!
On 5 May 2014 11:07, Tom Prince tom.prince@ualberta.net wrote:
Eventually, apilinks should just go away. I think I have convinced Michael (pydoctor's maintainer) that pydoctor should just genereate an objects.inv that sphinx can read. Then the regular :py:*: annoations can be used, rather than the apilinks ones (which interpert <> backwards anyway).
That doesn't address the issue of what to do in the mean time. Looking at the code, it looks very similar to what the builtin extlinks extension does; except that apilinks wants `path.to.object <title> and extlinks wants `title <path.to.object>`. (But I guess this doesn't address the issue of # in the links being put in the wrong place. But, https://twistedmatrix.com/documents/current/api/twisted.web.iweb.IRequest.ge... does exists (probably to make this kind of linking work.
Tom
On May 5, 2014, at 1:07 AM, Tom Prince tom.prince@ualberta.net wrote:
Eventually, apilinks should just go away. I think I have convinced Michael (pydoctor's maintainer) that pydoctor should just genereate an objects.inv that sphinx can read. Then the regular :py:*: annoations can be used, rather than the apilinks ones
This would be very nice. Did you file an actual bug on pydoctor or is this a conversation which will be momentarily forgotten? :)
(which interpert <> backwards anyway).
Yes, this annoyed me greatly. :-.
-glyph
Glyph glyph@twistedmatrix.com writes:
This would be very nice. Did you file an actual bug on pydoctor or is this a conversation which will be momentarily forgotten? :)
Not exactly, but https://bugs.launchpad.net/pydoctor/+bug/1246713 and https://bugs.launchpad.net/pydoctor/+bug/1287458 both document that solution.
On 6 May 2014 11:15, Tom Prince tom.prince@ualberta.net wrote:
Glyph glyph@twistedmatrix.com writes:
This would be very nice. Did you file an actual bug on pydoctor or is this a conversation which will be momentarily forgotten? :)
Not exactly, but https://bugs.launchpad.net/pydoctor/+bug/1246713
I tried to push this ticket forward and added a comments. Feedback is much appreciated.
https://bugs.launchpad.net/pydoctor/+bug/1287458 both document that solution.
I have submitted a patch for pydoctor
https://code.launchpad.net/~adiroiban/pydoctor/1287458-objects.inv/+merge/21...
I have created a new ticket to support linking based on objects.inv. Please add your feedback.
https://bugs.launchpad.net/pydoctor/+bug/1318325
Thanks!
participants (3)
-
Adi Roiban -
Glyph -
Tom Prince