Refactor package name to avoid conflicts

[geaaru]

cinder package name is used by Openstack Cinder module.

Can you refactor package name to mkdocs-cinder or other name ?

So, users could be have at same time both packages.

Thanks in advance

[chrissimpkins]

The package is pushed to PyPI as mkdocs-cinder. Do you need me to change it somewhere else?

[geaaru]

Yes, i need that you change cinder directory of the project in mkdocs_cinder or mkdocs-cinder or other.

To avoid this errors in Gentoo/Sabayon Linux:

>>> Installing (2 of 3) dev-python/mkdocs-cinder-0.15.0::geaaru
 * This package will overwrite one or more files that may belong to other
 * packages (see list below). You can use a command such as `portageq
 * owners / <filename>` to identify the installed package that owns a
 * file. If portageq reports that only one package owns a file then do
 * NOT file a bug report. A bug report is only useful if it identifies at
 * least two or more packages that are known to install the same file(s).
 * If a collision occurs and you can not explain where the file came from
 * then you should simply ignore the collision since there is not enough
 * information to determine if a real problem exists. Please do NOT file
 * a bug report at https://bugs.gentoo.org/ unless you report exactly
 * which two packages install the same file(s). See
 * https://wiki.gentoo.org/wiki/Knowledge_Base:Blockers for tips on how
 * to solve the problem. And once again, please do NOT file a bug report
 * unless you have completely understood the above message.
 * 
 * Detected file collision(s):
 * 
 * 	/usr/lib64/python2.7/site-packages/cinder/__init__.py
 * 	/usr/lib64/python2.7/site-packages/cinder/__init__.pyc
 * 	/usr/lib64/python2.7/site-packages/cinder/__init__.pyo
 * 
 * Searching all installed packages for file collisions...
 * 
 * Press Ctrl-C to Stop
 * 
 * sys-cluster/cinder-2014.2.3:2014.2-juno::geaaru
 * 	/usr/lib64/python2.7/site-packages/cinder/__init__.py
 * 	/usr/lib64/python2.7/site-packages/cinder/__init__.pyc
 * 	/usr/lib64/python2.7/site-packages/cinder/__init__.pyo
 * 
 * Package 'dev-python/mkdocs-cinder-0.15.0' NOT merged due to file

Thank you for your fast reply.

[chrissimpkins]

Do you manage either Gentoo package? The change would alter the way that users need to set the Cinder theme in their MkDocs yml files which will break every build that is currently out there. Is Gentoo using the PyPI version? If so is it possible to create a custom Gentoo package that uses the pathing that you need? We can add this information to the docs for Gentoo users if someone is willing to build and maintain it.

[geaaru]

Hi, i'm a Sabayon dev and Gentoo Proxy Maintainer dev and yes, my idea is push ebuild for cinder package to portage in the next days.
Can you create a different branch with a different versioning number that move path to a compliant destination ? I prefer avoid create a patch with a refactor for any new release and this is recommended by Gentoo rules. Patches could be always small. So, probably this means that i'm not sure that will be accepted by Gentoo devs.

In this way you can handle changes to code more easy between two branches and certainly in a better way of me.

For example:

• 0.x branch avoid to break api

• 1.x branch changes path (installable on Gentoo/Sabayon and in the future master branch)

This only an idea that however require effort so free to choice your way.

Tell me how you want move.

Thanks

[chrissimpkins]

Sure happy to create a new branch for this work. Will be back around to this project soon and will let you know.

[chrissimpkins]

I am prepared to push this branch for you. Can you either let me know the exact source (including paths) changes that you need to support your release workflow or submit a pull request with these changes and I will push them to a gentoo branch for you?

[geaaru]

Hi chrissimpkins,
thank you very much for your support. I think that if you move your code from cinder to mkdocs-cinder (or mkdocs_cinder) as package name there aren't then conflicts with Openstack Cinder module.

Can you bump then a release related to gentoo branch after refactor ?

[chrissimpkins]

I think that if you move your code from cinder to mkdocs-cinder (or mkdocs_cinder) as package name there aren't then conflicts with Openstack Cinder module.

This is where I am confused because we are already doing this. The Python/PyPI package is named "mkdocs-cinder":

cinder/setup.py

Line 7 in 3278848

name="mkdocs-cinder",

https://pypi.org/project/mkdocs-cinder/

There is a cinder directory in the project for the theme files but I am failing to see how there is a namespace collision that is causing problems on your end. Can you expand on the install process that you are using in #58 (comment)?

[geaaru]

Problems are connected to cinder directory of the project.

Currently, if you try to install ebuild of mkdocs-cinder without changes these are examples of installed files:

/usr/lib64/python3.6/site-packages/cinder/__init__.py
/usr/lib64/python3.6/site-packages/cinder/404.html
/usr/lib64/python3.6/site-packages/cinder/base.html
/usr/lib64/python3.6/site-packages/cinder/content.html
/usr/lib64/python3.6/site-packages/cinder/main.html
/usr/lib64/python3.6/site-packages/cinder/mkdocs_theme.yml
/usr/lib64/python3.6/site-packages/cinder/nav-sub.html
/usr/lib64/python3.6/site-packages/cinder/nav.html
/usr/lib64/python3.6/site-packages/cinder/toc.html
/usr/lib64/python3.6/site-packages/cinder/css
/usr/lib64/python3.6/site-packages/mkdocs_cinder-0.16.0-py3.6.egg-info/entry_points.txt
...
etc.

Directory /usr/lib64/python3.6/site-packages/cinder it's already used by Openstack Cinder and so if a user want both openstack cinder and mkdocs-cinder he can't.

So, for this conflicts there are two alternatives:

1. change cinder directory to mkdocs-cinder

2. manage change of cinder directory name directly from ebuild

Now, if you said me that cinder it's only a directory with fonts, imagess, etc. and I could rename directory cinder directly from ebuild I could do that without problems but fwis yeah it is created mkdocs_cinder package but entry_points.txt point to cinder directory (that it is used also by Openstack cinder project).

A solution could be move cinder directory of the project to mkdocs-cinder and change conseguently setup.py entry_points option and any link of the theme that point to cinder directory.

Main conflict file is this:

/usr/lib64/python3.6/site-packages/cinder/__init__.py

but i think that it's a bad idea share a python namespace between two projects.

Is it possible change cinder directory of the project ? What means for final users ?

Thank you again very very much for your support

[chrissimpkins]

Will need to check the MkDocs documentation to figure this issue out. As I recall, MkDocs specifies this naming for packages that are released through PyPI. I would not be prepared to eliminate PyPI releases to support this but I bet there is a workaround that will allow us to support both approaches. It may be possible to simply change the mkdocs specific metadata in the setup.py file so that we can preserve the use of cinder to specify the theme in the mkdocs yml settings file. If this breaks that setting then we break every build out there. We could bump to v1.0 to do this but I prefer to keep the theme name in the settings file cinder rather than mkdocs-cinder. If you come up with any information before I do about any of these issues please let me know.

[geaaru]

I will try to do some tests. But I don't think that will be possible maintains settings file with cinder and resolve conflicts. Import of mkdocs-cinder theme uses same python namespace resolution probably.

[chrissimpkins]

Ready to do this anytime. Just poke me when you want to work on it.

[geaaru]

Hi, I confirm that you can maintain cinder name with very few changes about setup.py.
See ebuild on my overlay: https://github.com/geaaru/geaaru_overlay/blob/master/dev-python/mkdocs-cinder/mkdocs-cinder-0.16.0.ebuild#L23

In general if you change setup.py for use a different directory:

cinder = cinder => cinder = mkdocs_cinder

then you can rename cinder directory to mkdocs_cinder without impact to users.

[chrissimpkins]

Thanks for the feedback! Your are able to build docs with cinder as the theme name when you use this pathing approach?

site_name: [YOURPROJECT]
theme: cinder
nav:
- Home: index.md

I will try to have a look at this during the upcoming week.

[geaaru]

Yes, as I wrote in the previous comment with that changes no impact for users.