Updated PyQt Documents - Feedback Please

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

Updated PyQt Documents - Feedback Please

Phil Thompson-5
I've made a new release of the PyQt documentation at...

https://pyqt.readthedocs.io

This is the first stage of creating complete PyQt5 documentation (similar to what was done with the PyQt4 documentation).

The documentation is created from 4 sources:

- "static" text files
- .sip files that provide the objects (modules, classes, enums etc) being documented with hooks
  for "description files"
- the Qt source code which provide the initial content of the description files
- the description files which will be updated over time (a long time!) to become more Pythonic
  as required.

The system is designed so that it can be updated with new PyQt and Qt releases without losing any user-written changes to the description files.

For the moment the description files are just stubs (lots of TODOs) because I wanted feedback on the overall structure before populating it from the Qt documentation.

There are lots of outstanding issues that will be addressed over time. For example, nested classes are only referenced from the class index (mainly an issue for the classes that implement enum flags).

Any feedback and suggestions for improvement are welcome.

Phil
_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Updated PyQt Documents - Feedback Please

Neil Jansen
I think it's a great improvement over what was there before.

My first criticism is that it's a bit confusing to get to the important part (the actual API documentation, which has been what a lot of people here were asking for), it's hidden in the lower right-hand corner ("Modules | Classes | Index").  Why not add these to the bulleted list, towards the top? 

Second, would it be possible to add a link from each PyQt5 class API page, to the official Qt5 API page?

On Fri, Sep 28, 2018 at 11:39 AM Phil Thompson <[hidden email]> wrote:
I've made a new release of the PyQt documentation at...

https://pyqt.readthedocs.io

This is the first stage of creating complete PyQt5 documentation (similar to what was done with the PyQt4 documentation).

The documentation is created from 4 sources:

- "static" text files
- .sip files that provide the objects (modules, classes, enums etc) being documented with hooks
  for "description files"
- the Qt source code which provide the initial content of the description files
- the description files which will be updated over time (a long time!) to become more Pythonic
  as required.

The system is designed so that it can be updated with new PyQt and Qt releases without losing any user-written changes to the description files.

For the moment the description files are just stubs (lots of TODOs) because I wanted feedback on the overall structure before populating it from the Qt documentation.

There are lots of outstanding issues that will be addressed over time. For example, nested classes are only referenced from the class index (mainly an issue for the classes that implement enum flags).

Any feedback and suggestions for improvement are welcome.

Phil
_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt

_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Updated PyQt Documents - Feedback Please

Damon Lynch
In reply to this post by Phil Thompson-5
On Fri, Sep 28, 2018 at 11:38 AM Phil Thompson <[hidden email]> wrote:


Any feedback and suggestions for improvement are welcome.



Hi Phil,

I agree it's a big improvement. Thank you.

I have a simple suggestion: make the  "use the latest version of PyQt5 no matter what version of Qt v5 you are using" much more visible. It's buried at the moment. For example, even a minor change like rewording "An Explanation of Version Numbers" to "Understanding the Correct Version to Install" would make it much clearer to the uninitiated.

Damon


--

On Fri, Sep 28, 2018 at 11:38 AM Phil Thompson <[hidden email]> wrote:
I've made a new release of the PyQt documentation at...

https://pyqt.readthedocs.io

This is the first stage of creating complete PyQt5 documentation (similar to what was done with the PyQt4 documentation).

The documentation is created from 4 sources:

- "static" text files
- .sip files that provide the objects (modules, classes, enums etc) being documented with hooks
  for "description files"
- the Qt source code which provide the initial content of the description files
- the description files which will be updated over time (a long time!) to become more Pythonic
  as required.

The system is designed so that it can be updated with new PyQt and Qt releases without losing any user-written changes to the description files.

For the moment the description files are just stubs (lots of TODOs) because I wanted feedback on the overall structure before populating it from the Qt documentation.

There are lots of outstanding issues that will be addressed over time. For example, nested classes are only referenced from the class index (mainly an issue for the classes that implement enum flags).

Any feedback and suggestions for improvement are welcome.

Phil
_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt


--

_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Updated PyQt Documents - Feedback Please

Phil Thompson-5
In reply to this post by Neil Jansen
On 28 Sep 2018, at 4:47 pm, Neil Jansen <[hidden email]> wrote:
>
> I think it's a great improvement over what was there before.
>
> My first criticism is that it's a bit confusing to get to the important part (the actual API documentation, which has been what a lot of people here were asking for), it's hidden in the lower right-hand corner ("Modules | Classes | Index").

...and the upper right corner (of every page). These are the normal places for indices in Sphinx-based documentation.

> Why not add these to the bulleted list, towards the top?

I'm not sure what you mean by "the bulleted list". Do you mean the first page?

> Second, would it be possible to add a link from each PyQt5 class API page, to the official Qt5 API page?

Yes, that will happen when the Qt docs get injected.

Thanks,
Phil
_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Updated PyQt Documents - Feedback Please

Kyle Altendorf
In reply to this post by Phil Thompson-5
On 2018-09-28 11:38, Phil Thompson wrote:
> I've made a new release of the PyQt documentation at...
>
> https://pyqt.readthedocs.io

> Any feedback and suggestions for improvement are welcome.


Thanks Phil.  While this isn't as big a deal for me I know that many
people without C++ background ask for this.

I second the suggestion to have a link to the C++ docs.  If you are
parsing the C++ source perhaps you could even provide GitHub links to
the C++ source?  Obviously an 'advanced' feature but it'd be handy at
times.  I also like aspects of their structure which could be applied
here.  I like the separation of methods overridden by a given class in
the C++ docs, though people do admittedly regularly miss the 'all
members' links in the Qt docs.  Also separation of static methods.  You
already have the signals separate.  You have the 'inherits' section, the
'inherited by' section is nice for navigating the opposite direction.

I don't by any means think the C++ docs should be a reference standard
to copy, but I do find many aspects useful.

Oh yeah, thumbs up for not SourceForge.  :]  Their frequent downtime has
been an annoyance.

Cheers,
-kyle
_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Updated PyQt Documents - Feedback Please

Phil Thompson-5
On 28 Sep 2018, at 5:10 pm, Kyle Altendorf <[hidden email]> wrote:

>
> On 2018-09-28 11:38, Phil Thompson wrote:
>> I've made a new release of the PyQt documentation at...
>> https://pyqt.readthedocs.io
>
>> Any feedback and suggestions for improvement are welcome.
>
>
> Thanks Phil.  While this isn't as big a deal for me I know that many people without C++ background ask for this.
>
> I second the suggestion to have a link to the C++ docs.  If you are parsing the C++ source perhaps you could even provide GitHub links to the C++ source?  Obviously an 'advanced' feature but it'd be handy at times.  I also like aspects of their structure which could be applied here.  I like the separation of methods overridden by a given class in the C++ docs, though people do admittedly regularly miss the 'all members' links in the Qt docs.  Also separation of static methods.  You already have the signals separate.  You have the 'inherits' section, the 'inherited by' section is nice for navigating the opposite direction.
>
> I don't by any means think the C++ docs should be a reference standard to copy, but I do find many aspects useful.
>
> Oh yeah, thumbs up for not SourceForge.  :]  Their frequent downtime has been an annoyance.

There's quite a lot of useful information that isn't currently shown - eg. whether a C++ method is virtual and/or protected. Also any object ownership changes. The problem is how to represent these clearly and concisely. It's further complicated by the fact that most method arguments don't have names.

Phil
_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Updated PyQt Documents - Feedback Please

Neil Jansen
In reply to this post by Phil Thompson-5
On Fri, Sep 28, 2018 at 11:58 AM Phil Thompson <[hidden email]> wrote:
...and the upper right corner (of every page). These are the normal places for indices in Sphinx-based documentation.

Not necessarily.  Here's Kenneth Reitz's Requests documentation for example: http://docs.python-requests.org/en/latest/ .. This is a well-documented Python package, nobody would argue otherwise.  It's considered a standard by many in the Python community. If you scroll down, you'll see "The API Documentation / Guide".
 
I'm not sure what you mean by "the bulleted list". Do you mean the first page?

Yes.
 
> Second, would it be possible to add a link from each PyQt5 class API page, to the official Qt5 API page?

Yes, that will happen when the Qt docs get injected.

That's great news.


_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Updated PyQt Documents - Feedback Please

David Cortesi
In reply to this post by Phil Thompson-5
The section on enums [0] needs two things. One, it badly needs to distinguish the relationship (or explicitly deny any relationship) to Python Enums [1]. The person who knows Python but little C++ might naturally expect to do settings.value('flag', type=IntEnum) (and indeed why not?)

Two, a little example code would be a big help. What is the syntax for "specifying the scope of the enum"?



_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Updated PyQt Documents - Feedback Please

Detlev Offenbach
Hi,

while talking about enums. I would like to know, if anybody is about (or has
done so) develop a tool to migrate old code to the new enum handling (maybe as
a preparatory step for PyQt6).

Detlev

Am Freitag, 28. September 2018, 23:48:45 CEST schrieb David Cortesi:

> The section on enums [0] needs two things. One, it badly needs to
> distinguish the relationship (or explicitly deny any relationship) to
> Python Enums [1]. The person who knows Python but little C++ might
> naturally expect to do settings.value('flag', type=IntEnum) (and indeed why
> not?)
>
> Two, a little example code would be a big help. What is the syntax for
> "specifying the scope of the enum"?
>
> [0] https://pyqt.readthedocs.io/en/latest/gotchas.html#enums
>
> [1] https://docs.python.org/3.6/library/enum.html

--
Detlev Offenbach
[hidden email]


_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Updated PyQt Documents - Feedback Please

Hans-Peter Jansen-2
In reply to this post by Phil Thompson-5
Am Freitag, 28. September 2018, 17:38:13 CEST schrieb Phil Thompson:
> I've made a new release of the PyQt documentation at...
>
> https://pyqt.readthedocs.io
>
Hmm, the link is down now. Any idea, where it is gone?

Pete


_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Updated PyQt Documents - Feedback Please

Phil Thompson-5
On 18/09/2019 16:45, Hans-Peter Jansen wrote:
> Am Freitag, 28. September 2018, 17:38:13 CEST schrieb Phil Thompson:
>> I've made a new release of the PyQt documentation at...
>>
>> https://pyqt.readthedocs.io
>>
> Hmm, the link is down now. Any idea, where it is gone?

Follow the link from the homepage.

Phil
_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt