Updated the references to the snippets and subsections.

This is done to surpress warnings that the (previously .rst) files are not
included in the TOCtree, as the :orphan: directive appears to be conflicting
with Sphinx.

Author: torsava

application-modules.rst

@@ -1,9 +1,9 @@
 Porting an application and a module in one package
 ==================================================
 
-.. include:: snippets/desc_application-modules.rst
+.. include:: snippets/desc_application-modules.inc
 
-.. include:: snippets/section_header.rst
+.. include:: snippets/section_header.inc
 
 
 Porting the specfile to Python 3
@@ -25,30 +25,30 @@ Let's take an example spec file and port it to illustrate the process. We start
    :language: spec
 
 
-.. include:: subsections/h2-modifications.rst
+.. include:: subsections/h2-modifications.inc
 
-.. include:: subsections/h3-subpackages.rst
+.. include:: subsections/h3-subpackages.inc
 
-.. include:: subsections/h4-python_provide.rst
+.. include:: subsections/h4-python_provide.inc
 
-.. include:: subsections/h4-description.rst
+.. include:: subsections/h4-description.inc
 
 
-.. include:: subsections/h3-build-requires.rst
+.. include:: subsections/h3-build-requires.inc
 
 As we will be including the executable (application) only in the Python 3 subpackage, you may be also able to get rid of some runtime dependencies (listed using the ``Requires:`` tags) in the Python 2 subpackage that were previously used only by the executable and are therefore no longer needed in that subpackage. However, figuring out what runtime dependencies are no longer needed is a problematic task, therefore if you are unsure of which dependencies can be omitted, you can skip this task.
 
-.. include:: subsections/h3-build.rst
+.. include:: subsections/h3-build.inc
 
-.. include:: subsections/h3-install.rst
+.. include:: subsections/h3-install.inc
 
-.. include:: subsections/h3-check.rst
+.. include:: subsections/h3-check.inc
 
 
 %files
 ^^^^^^
 
-.. include:: snippets/files_preamble.rst
+.. include:: snippets/files_preamble.inc
 
 You can reuse the current ``%files`` section for the Python 2 submodule by giving it the appropriate package name. You can keep it almost the same as before, just make sure that, where appropriate, it uses the new macros ``%{python2_sitelib}``, ``%{python2_sitearch}``, ``%{python2_version}`` or perhaps ``%{python2_version_nodots}``.
 
@@ -92,14 +92,14 @@ If you do think they want to depend on your application, and therefore the depen
 If you are unsure whether the package needs to depend on your application, open a BugZilla report for the package and ask the maintainer(s) to answer the question themselves.
 
 
-.. include:: subsections/h2-ported-specfile.rst
+.. include:: subsections/h2-ported-specfile.inc
 
 
 .. literalinclude:: specs/application-module.spec
    :language: spec
 
 
-.. include:: subsections/h2-diff.rst
+.. include:: subsections/h2-diff.inc
 
 
 .. literalinclude:: specs/application-module.spec

applications.rst

@@ -1,9 +1,9 @@
 Porting applications that happen to be written in Python
 ========================================================
 
-.. include:: snippets/desc_applications.rst
+.. include:: snippets/desc_applications.inc
 
-.. include:: snippets/section_header.rst
+.. include:: snippets/section_header.inc
 
 Porting the specfile to Python 3
 --------------------------------
@@ -18,7 +18,7 @@ So let's take an example spec file and port it to illustrate the process. We sta
    :language: spec
 
 
-.. include:: subsections/h2-modifications.rst
+.. include:: subsections/h2-modifications.inc
 
 
 BuildRequires and Requires
@@ -56,7 +56,7 @@ Furthermore, as in the preceding `build-section`_ section, you will frequently f
 
 In the install section, try substituting it with the new ``%py3_install`` macro, which should figure out what to do automatically. If that doesn't work, or if you're porting the ``%check`` section, just make sure that any custom scripts or commands are invoked by the new ``%{__python3}`` macro.
 
-.. include:: snippets/install_non-python-script.rst
+.. include:: snippets/install_non-python-script.inc
 
 %files
 ^^^^^^
@@ -66,14 +66,14 @@ In the files section you can regularly find the following macros: ``%{python2_si
 The files section may also contain the versioned executable, usually ``%{_bindir}/sample-exec-2.7`` in which case it should be substituted by ``%{_bindir}/sample-exec-%{python3_version}``.
 
 
-.. include:: subsections/h2-ported-specfile.rst
+.. include:: subsections/h2-ported-specfile.inc
 
 
 .. literalinclude:: specs/application.spec
    :language: spec
 
 
-.. include:: subsections/h2-diff.rst
+.. include:: subsections/h2-diff.inc
 
 
 .. literalinclude:: specs/application.spec

index.rst

@@ -61,7 +61,7 @@ In rare cases your package might not nicely fall into either of these categories
 1. Applications that happen to be written in Python
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: snippets/desc_applications.rst
+.. include:: snippets/desc_applications.inc
 
 *See:* :doc:`applications`
 
@@ -75,13 +75,13 @@ If your package is being imported by third-party projects, but does not have any
 3. An application and a module in one package
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: snippets/desc_application-modules.rst
+.. include:: snippets/desc_application-modules.inc
 
 *See:* :doc:`application-modules`
 
 4. Tools for programming in Python
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: snippets/desc_tools.rst
+.. include:: snippets/desc_tools.inc
 
 *See:* :doc:`tools`

modules.rst

@@ -3,7 +3,7 @@ Porting Python modules
 
 This section is for Python **packages that do not have any executables**. Usually, these are normal Python modules that are being imported by third-party projects.
 
-.. include:: snippets/section_header.rst
+.. include:: snippets/section_header.inc
 
 
 Porting the specfile to Python 3
@@ -21,27 +21,27 @@ Let's take an example spec file and port it to illustrate the process. We start
    :language: spec
 
 
-.. include:: subsections/h2-modifications.rst
+.. include:: subsections/h2-modifications.inc
 
-.. include:: subsections/h3-subpackages.rst
+.. include:: subsections/h3-subpackages.inc
 
-.. include:: subsections/h4-python_provide.rst
+.. include:: subsections/h4-python_provide.inc
 
-.. include:: subsections/h4-description.rst
+.. include:: subsections/h4-description.inc
 
-.. include:: subsections/h3-build-requires.rst
+.. include:: subsections/h3-build-requires.inc
 
-.. include:: subsections/h3-build.rst
+.. include:: subsections/h3-build.inc
 
-.. include:: subsections/h3-install.rst
+.. include:: subsections/h3-install.inc
 
-.. include:: subsections/h3-check.rst
+.. include:: subsections/h3-check.inc
 
 
 %files
 ^^^^^^
 
-.. include:: snippets/files_preamble.rst
+.. include:: snippets/files_preamble.inc
 
 You can reuse the current ``%files`` section for the Python 2 submodule by giving it the appropriate package name. You can keep it almost the same as before, just make sure that, where appropriate, it uses the new macros ``%{python2_sitelib}``, ``%{python2_sitearch}``, ``%{python2_version}`` or perhaps ``%{python2_version_nodots}``.
 
@@ -62,13 +62,13 @@ Accordingly we'll also add a ``%files`` section for the Python 3 subpackage. You
     %{python3_sitelib}/*
 
 
-.. include:: subsections/h2-ported-specfile.rst
+.. include:: subsections/h2-ported-specfile.inc
 
 
 .. literalinclude:: specs/module.spec
    :language: spec
 
-.. include:: subsections/h2-diff.rst
+.. include:: subsections/h2-diff.inc
 
 
 .. literalinclude:: specs/module.spec

subsections/h3-install.inc

@@ -11,4 +11,4 @@ After that, add the corresponding Python 3 install command, which will be either
     %py2_install
     %py3_install
 
-.. include:: /snippets/install_non-python-script.rst
+.. include:: /snippets/install_non-python-script.inc

tools.rst

@@ -1,9 +1,9 @@
 Porting tools for programming in Python
 =======================================
 
-.. include:: snippets/desc_tools.rst
+.. include:: snippets/desc_tools.inc
 
-.. include:: snippets/section_header.rst
+.. include:: snippets/section_header.inc
 
 
 Porting the specfile to Python 3
@@ -21,17 +21,17 @@ Let's take an example spec file and port it to illustrate the process. We start
    :language: spec
 
 
-.. include:: subsections/h2-modifications.rst
+.. include:: subsections/h2-modifications.inc
 
-.. include:: subsections/h3-subpackages.rst
+.. include:: subsections/h3-subpackages.inc
 
-.. include:: subsections/h4-python_provide.rst
+.. include:: subsections/h4-python_provide.inc
 
-.. include:: subsections/h4-description.rst
+.. include:: subsections/h4-description.inc
 
-.. include:: subsections/h3-build-requires.rst
+.. include:: subsections/h3-build-requires.inc
 
-.. include:: subsections/h3-build.rst
+.. include:: subsections/h3-build.inc
 
 
 %install
@@ -41,7 +41,7 @@ The ``%install`` section is perhaps the most crucial one, because we have to be
 
 First, in the same manner as in the preceding `build-section`_ section, it is advisable to upgrade the current Python 2 install command to use the new ``%py2_install`` macro, however, if that doesn't work for you, you can stick with the current install command, just make sure it's invoked by the ``%{__python2}`` macro. The corresponding Python 3 install command will then either be the custom command prefixed by ``%{__python3}`` or the new ``%py3_install`` macro, which I'll be using in this example.
 
-.. include:: snippets/install_non-python-script.rst
+.. include:: snippets/install_non-python-script.inc
 
 As the `packaging guidelines`_ specify, the Python 2 package is currently to be the default one, thus it is best if we first install the Python 3 version of our software and then the one for Python 2, because in case they are installing some files into the same directories (such as ``/usr/bin/``), one installation will overwrite the files of the other. So if we install the Python 2 version last, its files will be located in those shared directories.
 
@@ -77,13 +77,13 @@ What remains is to provide symlinks for the executables in the format ``executab
 Note that these symlinks use a relative path in relation to their location, i.e. they are pointing to a file that is at any given moment in the same directory as they are.
 
 
-.. include:: subsections/h3-check.rst
+.. include:: subsections/h3-check.inc
 
 
 %files
 ^^^^^^
 
-.. include:: snippets/files_preamble.rst
+.. include:: snippets/files_preamble.inc
 
 You can reuse the current ``%files`` section for the Python 2 submodule by giving it the appropriate package name. You can keep it almost the same as before, just make sure that, where appropriate, it uses the new macros ``%{python2_sitelib}``, ``%{python2_sitearch}``, ``%{python2_version}`` or perhaps ``%{python2_version_nodots}``. Finally, don't forget to add the two new locations of the executable we've made available through the symlinks.
 
@@ -109,14 +109,14 @@ Accordingly we'll also add a ``%files`` section for the Python 3 subpackage. You
     %{_bindir}/sample-exec-%{python3_version}
 
 
-.. include:: subsections/h2-ported-specfile.rst
+.. include:: subsections/h2-ported-specfile.inc
 
 
 .. literalinclude:: specs/tool.spec
    :language: spec
 
 
-.. include:: subsections/h2-diff.rst
+.. include:: subsections/h2-diff.inc
 
 
 .. literalinclude:: specs/tool.spec