Open emiliom opened 6 years ago
@lsetiawan, a question about the sphinx documentation: what happens once we merge your PR #146 (assuming it does what we want), in terms of the API Sphinx documentation? Now there'll be two valid module paths, one with the ODM2
path/package component, one without. Can we choose which one to show in the API documentation?
For reference, here's the API doc for readService
, which currently has the module path odm2api.ODM2.services.readService
. The new path would be odm2api.services.readService
, but the old one will still work.
For the sphinx, I'd probably have to update the rst
docs. See https://github.com/ODM2/ODM2PythonAPI/blob/master/docs/source/modules.rst. We would like to show the new ones correct? I'm not sure how the old one will render in the documentation. Thanks.
For the sphinx, I'd probably have to update the rst docs.
Ok. So we control that. Cool.
We would like to show the new ones correct?
Exactly
Done in #147. Closing.
Thanks for closing.
I guess regarding the docs:
For the sphinx, I'd probably have to update the rst docs. See https://github.com/ODM2/ODM2PythonAPI/blob/master/docs/source/modules.rst. We would like to show the new ones correct? I'm not sure how the old one will render in the documentation.
The updates should be done only when issue a new release.
I can update that now, so it will be included in the new release.
I can update that now, so it will be included in the new release.
Great, thanks.
I'm reopening this issue as a reminder that in a future release (date TBD), we'll remove support for the now-deprecated "ODM2" package module hierarchy. That, import statements such as this one:
odm2api.ODM2.services.readService
will eventually no longer be supported, and only the new hiearchy will be supported:
odm2api.services.readService
Note to self: Make sure to read #159 for "definitive" findings about the preservation of git history after the module moves.
We started discussing this some time ago at #135
@lsetiawan's PR #145 is intended to create a very nifty deprecation pathway to implement the reorganization and removal of the
ODM2
folder.Background discussions (copied from #135)
Emilio:
There's one issue that I think needs to be discussed soon, before odm2api can be seen as really stable. Currently the package has a packager/folder hierarchy that includes a now-useless "ODM2" folder: https://github.com/ODM2/ODM2PythonAPI/tree/master/odm2api/ODM2
That forces most module import statements to include the useless ODM2 package hierarchy (eg,
odm2api.ODM2.services.readService
). We'll need to get rid of the ODM2 folder hierarchy, and the sooner we do it the better, to minimize disruptions. I strongly recommend that we do it in the next release, giving ourselves plenty of time for all code that uses odm2api to make the adjustment.Anthony:
I'm very much a fan of moving forward soon with the next release to remove the useless "ODM2" level of hierarchy (clipped unrelated comment). With release v0.7 minted as is, any software that depends on the old conventions still have handy access to that version, while we can move forward with migrating our actively developed stuff to our widespread conventions.