Bug 988765

Can I help somehow to get this progressing?  What needs to be done?

(In reply to Suvayu from comment #1)
> Can I help somehow to get this progressing?  What needs to be done?

Sorry, I'm currently occupied with other work. If you can send me a patch, that is all the help I need :)

I took a quick look.  If you could guide me, I think I can make a
patch.

Question:

I think the tarball in python-docs actually has its own version of
sphinx inside.  This version does not seem to be in sync with the
version available in the Fedora repositories.  Is that correct?

I'm saying they are not in sync because I see the builders provided
are not the same.  Here is a comparison (from sphinx/builders):

| python-docs source tarball | python-sphinx package |
|----------------------------+-----------------------|
| changes.py                 | changes.py            |
| devhelp.py                 | devhelp.py            |
| epub.py                    | epub.py               |
|                            | gettext.py            |
| htmlhelp.py                | htmlhelp.py           |
| html.py                    | html.py               |
| latex.py                   | latex.py              |
| linkcheck.py               | linkcheck.py          |
| manpage.py                 | manpage.py            |
| qthelp.py                  | qthelp.py             |
|                            | texinfo.py            |
| text.py                    | text.py               |
|                            | websupport.py         |

Can you clarify this a bit?

I think I have figured this out.  The Makefile does an svn checkout to get the requires.  Instead of using the installed packages on the system.  The version of the tools it checks out are hardcoded.

checkout:
        @if [ ! -d tools/sphinx ]; then \
          echo "Checking out Sphinx..."; \
          svn checkout $(SVNROOT)/external/Sphinx-1.0.7/sphinx tools/sphinx; \
        fi
        @if [ ! -d tools/docutils ]; then \
          echo "Checking out Docutils..."; \
          svn checkout $(SVNROOT)/external/docutils-0.6/docutils tools/docutils; \
        fi
        # ... and so on

Created attachment 804460 [details]
patch to include info docs

I have attached a patch.  A few comments:

1. There is an image linked from the info file created under

     (info "(python) Logging Flow")

   I don't know what is the policy for a case like this.  I'm not sure
   how, the image is compressed before install.  This breaks the link
   when viewing the info page from Emacs.  I am not sure how to deal
   with this issue.  At the moment I have included the gzipped image
   file in the rpm anyway.

2. I checked with rpmlint, it warns about the image file not being
   utf8.  I don't know if this is important or not.

Other than these two issues I think this patch should be good.  You
can cleanly apply this on top of
git://pkgs.fedoraproject.org/python-docs.git master.

Please let me know if something is off.

Created attachment 804558 [details]
patch to deal with compressed image file

> 1. There is an image linked from the info file created under
> 
>      (info "(python) Logging Flow")
> 
>    I don't know what is the policy for a case like this.  I'm not sure
>    how, the image is compressed before install.  This breaks the link
>    when viewing the info page from Emacs.  I am not sure how to deal
>    with this issue.  At the moment I have included the gzipped image
>    file in the rpm anyway.

I added a gunzip in the %check section.  It works well, but I don't know if it is acceptable to do such things in %check.

Hi,

Any comments on my patches?  Are they adequate or do I need to address
any issues?

(In reply to Suvayu from comment #7)
> Hi,
> 
> Any comments on my patches?  Are they adequate or do I need to address
> any issues?

Hi Suvayu,
sorry for not responding sooner.
The patches look good to me. Have you considered sending them upstream? I guess they might accept, although they'll probably only take them for Python 3 branch.
If you're already a packager, I'd be happy to make you comaintainer of python-docs, if you wish. Otherwise I'll apply and build myself.
Thanks a lot for the effort!

Hi,

Thanks for taking a look :).  I am not very familiar with RPM packaging in general, or Fedora specific guidelines.  This was my first packaging related contribution to Fedora.

Time permitting, I'll try to follow up on your suggestion to get this included upstream.  If there is any success, I'll let you know on this bug, then you can drop the patches.

Cheers,

Hi. Slavek asked me to take this bug from now on as he can't attend to it time-wise.

I am very glad that you made the patches and submitted them, they are nicely done, however, there are a couple of small issues with them, which I would like to ask you to fix:

1) Thank you for noticing that the sphinx instance is being downloaded in the process. We have fixed the issue in the meantime (see patch18 in the package's repo), so you only need to patch the makefile to add the info files building command.

2) It is a convention in Fedora to append subpackage names to parent package names if possible, so while we could technically go with python-info-docs, the preferable variant is python-docs-info.

3) The subpackage's description should not be just the parent package's summary, because especially in this case, the name isn't self-explanatory, and description is useful to the user viewing it.

4) Unpacking and installing things in %check isn't allowed according to guidelines. %check is used mainly for test suites and similar applications to run. If you need to unzip the image file, you can do that after building the info docs in %build.

Other than that, it is a fine contribution. Now, if you would be so kind to fix the parts that I highlighted, I will be more than happy to apply the patch for you. By the way, I have done a sort of a spec cleanup, be sure to pull the changes.

Also, if you are interested in becoming a Fedora contributor, you can become one (see this guide:  https://fedoraproject.org/wiki/Join_the_package_collection_maintainers?rd=PackageMaintainers/Join ). We will help you as much as we can.

Created attachment 828437 [details]
Enable texinfo builder and create subpackage

Created attachment 828438 [details]
Tackle compressed image file for info page

This tries to tackle the compressed image file so that it is displayed correctly when viewing the info page.

Hi Tomas,

I updated my patches based on your comments.  I'm attaching 2 patches: first enables the texinfo builder, and creates a subpackage.  The second one tries to address the image file (logging_flow.png) included with the docs.  The first patch is clean, however I'm not sure about the second one.

Here is the problem; I copy the info and png files in %install to %{buildroot}%{_infodir}.  This is well-and-good, but when rpm sees a file in %{_infodir} it compresses it.  So I have to list the gzipped versions in %files.  When I open the info page in Emacs, the image is not shown (I think it can't show compressed images).  So I have added the uncompress command in %post.  And I compress it again in %preun so that rpm can remove the image file properly.  The unfortunate side-effect is, now the following will not work:

$ rpm -qf /usr/share/info/logging_flow.png
file /usr/share/info/logging_flow.png is not owned by any package

I don't know what is the appropriate thing to do here.  If you think all of this is too messy, and it is fine to just leave the image compressed, then just don't apply my second patch.

About becoming a contributor, I have a FAS account but I'm very short on time usually.  I would be willing to help with python-docs though.  I think I am getting used to packaging.  Recently I also started maintaining a couple of packages on Fedora copr (mutt-kz and notmuch).

Thanks for the new patches. I'll apply the first one, while fixing some minor things (e. g. "rm -rf $RPM_BUILD_ROOT" is not necessary any more).

As for the compressed image, that's a bit of an issue here. I would like to ask you if you know details on how the file is used/viewed by emacs (I, myself, use Vim, so I don't know). I am afraid we can't work directly around the file being stored in _infodir uncompressed, but it might be possible to store it in _docdir and tell emacs to look there.

Okay, I'll take a look at the image (in 2-3 days).  I think it is
possible to edit the info or texi file with sed and point to a
different location.  For now, just keeping the compressed image is
okay I think.

My reasoning is two-fold:
1. the info viewer in the terminal can't show it anyway,
2. the info page in Emacs is still fine, it just says there is an
   image here which is not shown. Example (from the gnutls info page):

    [broken image:gnutls-client-server-use-case.png]

   So we also have other examples of this in Fedora :).

Created attachment 828856 [details]
Tackle compressed image file for info page

This patch deals with the image file by pointing to the same image used by the html docs.  I do this by editing the info file with sed in the %install section.  I hope you like this solution. :)

Thank you for this solution, it is cool. I am not sure if we actually need any other one at all. I will only change the path that you use (relative to the original image with hardcoded version) to absolute with %{_docdir}. The reason is that we have two packages - python-docs and python3-docs, and we want the difference between the specs to be as small as possible, plus it is generally preferred to use full paths with macros in SPEC files. 

I will not require you to make another patch, I will apply your patches in their entirety and change the SPEC after that. You will be able to view the results in git shortly.

As for the version of Fedora we fix this in, I am very reluctant to push this change to Fedora 18 as it's nearing its end of life. However, I have no objections to push this into F19 and newer. Is that okay with you?

This is not a critical change, it is just a convenience.  So applying this on Fedora 19 is just fine.  Thank you for helping me to get to an acceptable patch with your comments.  :)

python-docs-2.7.5-5.fc20 has been submitted as an update for Fedora 20.
https://admin.fedoraproject.org/updates/python-docs-2.7.5-5.fc20

python-docs-2.7.5-5.fc19 has been submitted as an update for Fedora 19.
https://admin.fedoraproject.org/updates/python-docs-2.7.5-5.fc19

The update for F19 and F20 was created. Once it is pushed to the Testing repo, you can install it by running

# yum install python-docs --enablerepo=updates-testing

The version where it's fixed is 2.7.5-5, so there is no point installing anything older. If the package works well for you, you can assign karma to it to speed up inclusion in the Updates repo. (more about it here: https://fedoraproject.org/wiki/QA:Updates_Testing?rd=QA/Updates_Testing ).

Package python-docs-2.7.5-5.fc20:
* should fix your issue,
* was pushed to the Fedora 20 testing repository,
* should be available at your local mirror within two days.
Update it with:
# su -c 'yum update --enablerepo=updates-testing python-docs-2.7.5-5.fc20'
as soon as you are able to.
Please go to the following url:
https://admin.fedoraproject.org/updates/FEDORA-2013-22269/python-docs-2.7.5-5.fc20
then log in and leave karma (feedback).

Hi Tomas,

The update finally went through to updates-testing; however I see a (minor) problem.  The image path is not correct after switching to %{_docdir} in the SPEC file.  This generates a path like this:

  /usr/share/doc/python-docs/html/_images/logging_flow.png

This is incorrect.  It should be:

  /usr/share/doc/python-docs-2.7.5/html/_images/logging_flow.png

I think this can be resolved by using the %{version} macro.  So maybe try something like this:

  sed -i -e 's,logging_flow\.png,%{_docdir}-%{version}/%{name}/html/_images/&,' \
       %{buildroot}%{_infodir}/python.info

Created attachment 831322 [details]
Fix image path

My earlier comment had the version macro at the wrong place.  This patch should fix the problem properly.

python-docs-2.7.5-6.fc19 has been submitted as an update for Fedora 19.
https://admin.fedoraproject.org/updates/python-docs-2.7.5-6.fc19

python-docs-2.7.5-6.fc20 has been submitted as an update for Fedora 20.
https://admin.fedoraproject.org/updates/python-docs-2.7.5-6.fc20

Thank you for pointing that out, it was indeed wrong. However, there is a macro specifically for that - %{_pkgdocdir}. This evaluates to %{_docdir}/%{name}-%{version} on F19 and earlier, and to %{_docdir}/%{name} on F20 and further.

New release (2.7.5-6) headed your way.

Thank you :)

This message is a reminder that Fedora 18 is nearing its end of life.
Approximately 4 (four) weeks from now Fedora will stop maintaining
and issuing updates for Fedora 18. It is Fedora's policy to close all
bug reports from releases that are no longer maintained. At that time
this bug will be closed as WONTFIX if it remains open with a Fedora 
'version' of '18'.

Package Maintainer: If you wish for this bug to remain open because you
plan to fix it in a currently maintained version, simply change the 'version' 
to a later Fedora version prior to Fedora 18's end of life.

Thank you for reporting this issue and we are sorry that we may not be 
able to fix it before Fedora 18 is end of life. If you would still like 
to see this bug fixed and are able to reproduce it against a later version 
of Fedora, you are encouraged  change the 'version' to a later Fedora 
version prior to Fedora 18's end of life.

Although we aim to fix as many bugs as possible during every release's 
lifetime, sometimes those efforts are overtaken by events. Often a 
more recent Fedora release includes newer upstream software that fixes 
bugs or makes them obsolete.

Fedora 18 changed to end-of-life (EOL) status on 2014-01-14. Fedora 18 is
no longer maintained, which means that it will not receive any further
security or bug fix updates. As a result we are closing this bug.

If you can reproduce this bug against a currently maintained version of
Fedora please feel free to reopen this bug against that version. If you
are unable to reopen this bug, please file a new report against the
current release. If you experience problems, please add a comment to this
bug.

Thank you for reporting this bug and we are sorry it could not be fixed.

Any reason this update is still sitting in updates-testing?

python-docs-2.7.5-6.fc19 has been pushed to the Fedora 19 stable repository.  If problems still persist, please make note of it in this bug report.

python-docs-2.7.5-6.fc20 has been pushed to the Fedora 20 stable repository.  If problems still persist, please make note of it in this bug report.