Naming a sphinx-doc theme: python-sphinx_py3doc_enhanced_theme or python-sphinx-theme-py3doc-enhanced

[Julien Enselme]

Hi,

Recently I opened a review [1] for a new sphinx theme:
py3doc_enhanced_theme [2]

The upstream name is sphinx_py3doc_enhanced_theme, so in my opinion,
the the package should be named python-sphinx_py3doc_enhanced_theme.
Furthermore, there's another sphinx theme with underscores in its
name: python3-sphinx_rtd_theme. So I find it logical that the package
is named this way.

However, the reviewer (Zbigniew Jędrzejewski-Szmek) pointed out that:

- Dashes are preferred (See the guidelines [3])
- Most themes are named with this pattern: python-sphinx-theme-<name>
Therefore, it would be consistent to name the package: python-sphinx-
theme-py3doc-enhanced and I think that's a good point.

A middle ground would be to use provides so the package can be
installed with both names, but that leaves the question about the
"main" name unresolved.

Any thoughts?

BTW, I though there was a wiki page about packaging sphinx themes but I
can't find it out. Does it ring a bell to anyone?

[1] https://bugzilla.redhat.com/show_bug.cgi?id=1367699
[2] https://pypi.python.org/pypi/sphinx_py3doc_enhanced_theme
[3] https://fedoraproject.org/wiki/Packaging:Naming?rd=Packaging:Naming
Guidelines#Separators

Regards,
-- 
Julien Enselme
http://www.jujens.eu/

[Garrett Holmstrom]

On 2016-08-23 10:19, Julien Enselme wrote:
>  Hi,
>
>  Recently I opened a review [1] for a new sphinx theme:
>  py3doc_enhanced_theme [2]
>
>  The upstream name is sphinx_py3doc_enhanced_theme, so in my opinion,
>  the the package should be named python-sphinx_py3doc_enhanced_theme.
>  Furthermore, there's another sphinx theme with underscores in its
>  name: python3-sphinx_rtd_theme. So I find it logical that the package
>  is named this way.
>
>  However, the reviewer (Zbigniew Jędrzejewski-Szmek) pointed out that:
>
>  - Dashes are preferred (See the guidelines [3])
>  - Most themes are named with this pattern: python-sphinx-theme-<name>
>  Therefore, it would be consistent to name the package: python-sphinx-
>  theme-py3doc-enhanced and I think that's a good point.
>
>  A middle ground would be to use provides so the package can be
>  installed with both names, but that leaves the question about the
>  "main" name unresolved.
>
>  Any thoughts? 
Using hyphens in the package name keeps the package collection more 
consistent, and adding a Provides entry that uses underscores will more 
or less seamlessly take care of the case where people installing it 
assume it uses those instead.  It's a win-win to do it that way, IMO.

-- 
Garrett Holmstrom

[Avram Lubkin]

Frankly I think upstream should have called it py3doc_enhanced and left out
sphinx and theme, but that's beside the point.

Based on the package naming conventions [1], you name is mainly correct
(more on this later). In the Python modules section [2], it says:

The package name should reflect the upstream name of the Python module, and
should generally take into account the name of the module used when
importing it in Python scripts. This name will be prefixed depending on the
type of the package.

Based on that, the name should really be
python-sphinx-theme-sphinx_py3doc_enhanced_theme,
but that is overly confusing. I think there are two legitimate names:

python-sphinx-theme-py3doc_enhanced
python-sphinx_py3doc_enhanced_theme

Some might argue you could replace the underscore in the first one with a
dash, and I wouldn't see a huge problem with that, but I think it's not
necessary. It is justified though because the name is already changed from
the import name and the tarball for the package uses dashes instead of
underscores.

As far those underscores, that's covered in the separator section [3]:

There are a few exceptions to the no underscore '_' rule.
...
- packages where the upstream name naturally contains an underscore are
excluded from this.

Based on this rule and the Python module rule, I would say python-
sphinx-py3doc-enhanced-theme would not be an appropriate name.

So go with one of these:

python-sphinx-theme-py3doc_enhanced
python-sphinx-theme-py3doc-enhanced
python-sphinx_py3doc_enhanced_theme


[1] https://fedoraproject.org/wiki/Packaging:Naming
[2] https://fedoraproject.org/wiki/Packaging:Naming?rd=
Packaging:NamingGuidelines#Python_modules
[3] https://fedoraproject.org/wiki/Packaging:Naming?rd=
Packaging:NamingGuidelines#Separators

On Wed, Aug 24, 2016 at 3:16 AM, Garrett Holmstrom <gholms(a)fedoraproject.org
>  wrote: 
>  On 2016-08-23 10:19, Julien Enselme wrote:
>
> > Hi,
> >
> > Recently I opened a review [1] for a new sphinx theme:
> > py3doc_enhanced_theme [2]
> >
> > The upstream name is sphinx_py3doc_enhanced_theme, so in my opinion,
> > the the package should be named python-sphinx_py3doc_enhanced_theme.
> > Furthermore, there's another sphinx theme with underscores in its
> > name: python3-sphinx_rtd_theme. So I find it logical that the package
> > is named this way.
> >
> > However, the reviewer (Zbigniew Jędrzejewski-Szmek) pointed out that:
> >
> > - Dashes are preferred (See the guidelines [3])
> > - Most themes are named with this pattern: python-sphinx-theme-<name>
> > Therefore, it would be consistent to name the package: python-sphinx-
> > theme-py3doc-enhanced and I think that's a good point.
> >
> > A middle ground would be to use provides so the package can be
> > installed with both names, but that leaves the question about the
> > "main" name unresolved.
> >
> > Any thoughts?
> >
>
>  Using hyphens in the package name keeps the package collection more
>  consistent, and adding a Provides entry that uses underscores will more or
>  less seamlessly take care of the case where people installing it assume it
>  uses those instead.  It's a win-win to do it that way, IMO.
>
>  --
>  Garrett Holmstrom
>  --
>  devel mailing list
>  devel(a)lists.fedoraproject.org
>  https://lists.fedoraproject.org/admin/lists/[e-mail]
>

[Julien Enselme]

Thanks for your responses. I think I'll use 

- As the main name for the package: python-sphinx-theme-py3doc-enhanced
- A provide for python-sphinx_py3doc_enhanced_theme

This way it can be installed with a nice and consistant name as well
with its upstream name.

On Wed, 2016-08-24 at 10:25 -0400, Avram Lubkin wrote:
>  
>  Frankly I think upstream should have called it py3doc_enhanced and
>  left out sphinx and theme, but that's beside the point.
>  
>  Based on the package naming conventions [1], you name is mainly
>  correct (more on this later). In the Python modules section [2], it
>  says:
>  
>  The package name should reflect the upstream name of the Python
>  module, and should generally take into account the name of the module
>  used when importing it in Python scripts. This name will be prefixed
>  depending on the type of the package.
>  
>  Based on that, the name should really be python-sphinx-theme-
>  sphinx_py3doc_enhanced_theme, but that is overly confusing. I think
>  there are two legitimate names:
>  
>  python-sphinx-theme-py3doc_enhanced
>  python-sphinx_py3doc_enhanced_theme
>  
>  Some might argue you could replace the underscore in the first one
>  with a dash, and I wouldn't see a huge problem with that, but I think
>  it's not necessary. It is justified though because the name is
>  already changed from the import name and the tarball for the package
>  uses dashes instead of underscores.
>  
>  As far those underscores, that's covered in the separator section
>  [3]:
>  
>  There are a few exceptions to the no underscore '_' rule.
>  ...
>  - packages where the upstream name naturally contains an underscore
>  are excluded from this.
>  
>  Based on this rule and the Python module rule, I would say python-
>  sphinx-py3doc-enhanced-theme would not be an appropriate name.
>  
>  So go with one of these:
>  
>  python-sphinx-theme-py3doc_enhanced
>  python-sphinx-theme-py3doc-enhanced
>  python-sphinx_py3doc_enhanced_theme
>  
>  
>  [1] https://fedoraproject.org/wiki/Packaging:Naming
>  [2] https://fedoraproject.org/wiki/Packaging:Naming?rd=Packaging:Nami
>  ngGuidelines#Python_modules
>  [3] https://fedoraproject.org/wiki/Packaging:Naming?rd=Packaging:Nami
>  ngGuidelines#Separators
>  
>  On Wed, Aug 24, 2016 at 3:16 AM, Garrett Holmstrom <gholms@fedoraproj
>  ect.org> wrote:
>  > 
>  > On 2016-08-23 10:19, Julien Enselme wrote:
>  > > 
>  > > Hi,
>  > > 
>  > > Recently I opened a review [1] for a new sphinx theme:
>  > > py3doc_enhanced_theme [2]
>  > > 
>  > > The upstream name is sphinx_py3doc_enhanced_theme, so in my
>  > > opinion,
>  > > the the package should be named python-
>  > > sphinx_py3doc_enhanced_theme.
>  > > Furthermore, there's another sphinx theme with underscores in its
>  > > name: python3-sphinx_rtd_theme. So I find it logical that the
>  > > package
>  > > is named this way.
>  > > 
>  > > However, the reviewer (Zbigniew Jędrzejewski-Szmek) pointed out
>  > > that:
>  > > 
>  > > - Dashes are preferred (See the guidelines [3])
>  > > - Most themes are named with this pattern: python-sphinx-theme-
>  > > <name>
>  > > Therefore, it would be consistent to name the package: python-
>  > > sphinx-
>  > > theme-py3doc-enhanced and I think that's a good point.
>  > > 
>  > > A middle ground would be to use provides so the package can be
>  > > installed with both names, but that leaves the question about the
>  > > "main" name unresolved.
>  > > 
>  > > Any thoughts?
>  > > 
>  >  
>  > Using hyphens in the package name keeps the package collection more
>  > consistent, and adding a Provides entry that uses underscores will
>  > more or less seamlessly take care of the case where people
>  > installing it assume it uses those instead.  It's a win-win to do
>  > it that way, IMO.
>  > 
>  > --
>  > devel mailing list
>  > devel(a)lists.fedoraproject.org
>  > https://lists.fedoraproject.org/admin/lists/[e-mail]
>  > ct.org
>  >  
-- 
Julien Enselme
http://www.jujens.eu/
-- 
Julien Enselme
http://www.jujens.eu/