Update Guide to 54e8321

Signed-off-by: Michał Górny <mgorny@gentoo.org>

1 files changed, 22 insertions, 32 deletions

diff --git a/guide/concept.html b/guide/concept.html
index 30fd9fe..56284dd 100644
--- a/guide/concept.html
+++ b/guide/concept.html
@@ -136,54 +136,43 @@ of <code class="docutils literal notranslate"><span class="pre">__init__.py</spa
 they do not require any specific action, distinguishing them is not very
 important.</p>
 <p>pkgutil namespaces can be recognized through the content of their
-<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>.  Generally, you should find it suspicious if is
+<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>.  Generally, you should find it suspicious if it is
 the only file in a top-level package directory, and if the name of this
 directory is less specific than the package name (e.g. <code class="docutils literal notranslate"><span class="pre">zope</span></code> for
 <code class="docutils literal notranslate"><span class="pre">zope.interface</span></code>, <code class="docutils literal notranslate"><span class="pre">ruamel</span></code> for <code class="docutils literal notranslate"><span class="pre">ruamel.yaml</span></code>).  If you miss this,
-then you will learn about the namespace from package collisions
-on the respective <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>.</p>
+then you will learn about it when the <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file collides
+between multiple packages.</p>
 <p>setuptools namespaces usually do not install <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> but
-do install a <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file instead.  The distutils-r1 eclass detects
-this automatically and prints a warning.  Prior to installation,
-they can also be recognized by <code class="docutils literal notranslate"><span class="pre">namespace_packages</span></code> option
-in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> or <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>.</p>
+do install a <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file instead.  Prior to installation, they can
+also be recognized by <code class="docutils literal notranslate"><span class="pre">namespace_packages</span></code> option in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>
+or <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>.  However, some packages use a custom <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>
+file that does enable setuptools namespaces.</p>
 </section>
 <section id="adding-new-namespace-packages-to-gentoo">
 <h3>Adding new namespace packages to Gentoo<a class="headerlink" href="#adding-new-namespace-packages-to-gentoo" title="Permalink to this heading">¶</a></h3>
 <p>If the package uses PEP 420 namespaces, no special action is required.
 Per PEP 420 layout, the package must not install <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files
 for namespaces.</p>
-<p>If the package uses one of the other layouts, their respective files
-must be removed from the install tree.</p>
-<p>For pkgutil namespace, its <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> should be removed after
-the PEP 517 build phase:</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_compile<span class="o">()</span><span class="w"> </span><span class="o">{</span>
-<span class="w">    </span>distutils-r1_python_compile
-<span class="w">    </span>rm<span class="w"> </span><span class="s2">&quot;</span><span class="si">${</span><span class="nv">BUILD_DIR</span><span class="si">}</span><span class="s2">/install</span><span class="k">$(</span>python_get_sitedir<span class="k">)</span><span class="s2">&quot;</span>/jaraco/__init__.py<span class="w"> </span><span class="o">||</span><span class="w"> </span>die
-<span class="o">}</span>
+<p>If the package uses the regular setuptools namespace install method
+(i.e. <code class="docutils literal notranslate"><span class="pre">namespace_packages</span></code> option), then the eclass detects that
+and strips the namespaces automatically, e.g.:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="o">*</span> <span class="n">python3_11</span><span class="p">:</span> <span class="n">running</span> <span class="n">distutils</span><span class="o">-</span><span class="n">r1_run_phase</span> <span class="n">distutils</span><span class="o">-</span><span class="n">r1_python_install</span>
+<span class="o">*</span> <span class="n">Stripping</span> <span class="n">pkg_resources</span><span class="o">-</span><span class="n">style</span> <span class="n">namespace</span> <span class="n">ruamel</span>
+<span class="o">*</span> <span class="n">Stripping</span> <span class="n">pkg_resources</span><span class="o">-</span><span class="n">style</span> <span class="n">namespace</span> <span class="n">ruamel</span><span class="o">.</span><span class="n">std</span>
 </pre></div>
 </div>
-<p>The equivalent code for the legacy eclass mode is:</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_install<span class="o">()</span><span class="w"> </span><span class="o">{</span>
-<span class="w">    </span>rm<span class="w"> </span><span class="s2">&quot;</span><span class="si">${</span><span class="nv">BUILD_DIR</span><span class="si">}</span><span class="s2">&quot;</span>/lib/jaraco/__init__.py<span class="w"> </span><span class="o">||</span><span class="w"> </span>die
-<span class="w">    </span>distutils-r1_python_install
-<span class="o">}</span>
-</pre></div>
-</div>
-<p>For setuptools namespace, the <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file should be removed instead:</p>
+<p>If the package uses pkgutil-style or setuptools-style namespaces
+via <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files, these files need to be removed manually.
+This is done after the PEP 517 build phase:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_compile<span class="o">()</span><span class="w"> </span><span class="o">{</span>
 <span class="w">    </span>distutils-r1_python_compile
-<span class="w">    </span>find<span class="w"> </span><span class="s2">&quot;</span><span class="si">${</span><span class="nv">BUILD_DIR</span><span class="si">}</span><span class="s2">&quot;</span><span class="w"> </span>-name<span class="w"> </span><span class="s1">&#39;*.pth&#39;</span><span class="w"> </span>-delete<span class="w"> </span><span class="o">||</span><span class="w"> </span>die
-<span class="o">}</span>
-</pre></div>
-</div>
-<p>The setuptools code for the legacy mode is:</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_install_all<span class="o">()</span><span class="w"> </span><span class="o">{</span>
-<span class="w">    </span>distutils-r1_python_install_all
-<span class="w">    </span>find<span class="w"> </span><span class="s2">&quot;</span><span class="si">${</span><span class="nv">D</span><span class="si">}</span><span class="s2">&quot;</span><span class="w"> </span>-name<span class="w"> </span><span class="s1">&#39;*.pth&#39;</span><span class="w"> </span>-delete<span class="w"> </span><span class="o">||</span><span class="w"> </span>die
+<span class="w">    </span>rm<span class="w"> </span><span class="s2">&quot;</span><span class="si">${</span><span class="nv">BUILD_DIR</span><span class="si">}</span><span class="s2">/install</span><span class="k">$(</span>python_get_sitedir<span class="k">)</span><span class="s2">&quot;</span>/jaraco/__init__.py<span class="w"> </span><span class="o">||</span><span class="w"> </span>die
 <span class="o">}</span>
 </pre></div>
 </div>
+<p>Note that in some extreme cases, upstream combines namespace support
+and other code in the <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file.  Naturally, this file cannot
+be removed.  No good solution has been found for this problem yet.</p>
 <p>Some packages include an explicit <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> runtime dependency
 (<code class="docutils literal notranslate"><span class="pre">install_requires</span></code>) when using namespaces.  If this is the only
 use of <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> and <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> in installed package
@@ -232,10 +221,11 @@ of being retired.</p>
 <li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li>
 <li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li>
 <li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li>
+<li class="toctree-l1"><a class="reference internal" href="test.html">Tests in Python packages</a></li>
 <li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li>
+<li class="toctree-l1"><a class="reference internal" href="pypi.html">pypi — helper eclass for PyPI archives</a></li>
 <li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li>
-<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li>
 <li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Advanced concepts</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#namespace-packages">Namespace packages</a></li>