Lots of docs changes landing soon

wxPython Dev
1

Hi all,

For the past few weeks I've been hammering on the sphinx generator and docs processing code. I started out to make one change and now have around 70 commits on this branch! It seemed that for every change I made I found one or two others that I needed or wanted to do also. See the summary of changes below.

I'll be merging the branch shortly, but unfortunately it's going to necessitate some changes in the docstrings in the Python modules in wx.lib and etc. This is something that you guys can help out with via PRs if you have some time and desire to contribute. Basically the main change needed is to fully qualify the names of wx types and functions in the docstrings, both in explicit references like :class:, :meth: or :ref: and also in param lists that are specifying a wx class type. For example, some of the modules may have already been updated to use ref's with names like Window, Control, or Size, and they need to be changed to wx.Window, wx.Control and wx.Size. Only items that are deinfed within the same module do not need to be changed to fully qualified names. You can see the type of changes I'm talking about in this commit:

  https://github.com/RobinD42/Phoenix/commit/dd552ce67036d43889a69ccbf4db54546aa53f87

Other updates to the docstrings while you are working on the modules, like more complete docs coverage, fleshing out the module and class docs to give more explanations or examples, etc., would also be appreciated.

Summary of some of the bigger changes:

* The "wx." prefix is now used everywhere, and I think it helps the docs be less ambiguous, both from the human perspective and also for Sphinx.

* All the extension modules now have their own module docstring and it is now used on the module docs pages instead of boilerplate text.

* A summary of the functions in an extension module are listed on the module doc page below the class summary.

* Updated the index and API main page, cleaning out some out-dated boilerplate text and updated or added some others.

* Tweaked the page layout a bit, moving the search box to the side bar, reducing the height of the fixed portion at the top, etc.

* Also tweaked the CSS some, there's probably still more to be done there. Upgrading the version of Sphinx being used has caused some other style changes as well.

* Lots of refactoring and other fixes along the way.

See https://github.com/wxWidgets/Phoenix/pull/83

···

--
Robin Dunn
Software Craftsman
http://wxPython.org

2

Hi Robin,

···

On Saturday, June 11, 2016 at 3:39:16 PM UTC-5, Robin Dunn wrote:

Hi all,

For the past few weeks I’ve been hammering on the sphinx generator and
docs processing code. I started out to make one change and now have
around 70 commits on this branch! It seemed that for every change I
made I found one or two others that I needed or wanted to do also. See
the summary of changes below.

I’ll be merging the branch shortly, but unfortunately it’s going to
necessitate some changes in the docstrings in the Python modules in
wx.lib and etc. This is something that you guys can help out with via
PRs if you have some time and desire to contribute. Basically the main
change needed is to fully qualify the names of wx types and functions in
the docstrings, both in explicit references like :class:, :meth: or
:ref: and also in param lists that are specifying a wx class type. For
example, some of the modules may have already been updated to use ref’s
with names like Window, Control, or Size, and they need to be changed to
wx.Window, wx.Control and wx.Size. Only items that are deinfed within
the same module do not need to be changed to fully qualified names. You
can see the type of changes I’m talking about in this commit:

    [https://github.com/RobinD42/Phoenix/commit/dd552ce67036d43889a69ccbf4db54546aa53f87](https://github.com/RobinD42/Phoenix/commit/dd552ce67036d43889a69ccbf4db54546aa53f87)

Other updates to the docstrings while you are working on the modules,
like more complete docs coverage, fleshing out the module and class docs
to give more explanations or examples, etc., would also be appreciated.

Summary of some of the bigger changes:

  • The “wx.” prefix is now used everywhere, and I think it helps the docs
    be less ambiguous, both from the human perspective and also for Sphinx.

  • All the extension modules now have their own module docstring and it
    is now used on the module docs pages instead of boilerplate text.

  • A summary of the functions in an extension module are listed on the
    module doc page below the class summary.

  • Updated the index and API main page, cleaning out some out-dated
    boilerplate text and updated or added some others.

  • Tweaked the page layout a bit, moving the search box to the side bar,
    reducing the height of the fixed portion at the top, etc.

  • Also tweaked the CSS some, there’s probably still more to be done
    there. Upgrading the version of Sphinx being used has caused some other
    style changes as well.

  • Lots of refactoring and other fixes along the way.

See https://github.com/wxWidgets/Phoenix/pull/83

–
Robin Dunn

Software Craftsman

http://wxPython.org

Someone on the IRC channel mentioned that Google’s indexers aren’t picking up the new changes. So if I go look up “wxPython phoenix sizer” for example, Google returns http://wxpython.org/Phoenix/docs/html/Sizer.html which leads to a 404 page. The correct page is wx.Sizer — wxPython Phoenix 4.2.3a1 documentation now, but for some reason Google isn’t finding it.

Just an FYI.

  • Mike