- Create a directory with the name
adafruit_library
where "library" is the name- Note: CASE matters. Make it all lowercase
- Add an
__init__.py
file to the directory- Let Python know that the directory can be imported
- File can be empty
- Update
setup.py
- Change
py_modules=[...]
to 'packages=[...]`
- Change
- Move the existing module to the new directory
- Use
git mv
to keep the full history - Drop the "adafruit" prefix from the filenames
git mv adafruit_filename.py ./adafruit_library/filename.py
- Update the name of the module at the top of the file to its new name. This is for Sphinx to be able to reference the module.
- For example, if the library was "adafruit_filename", it would change as below...
- Use
SPDX-License....
`adafruit_filename` # <--- This changes...
`filename` # <--- ...to this.
================================================================================
The documentation is generated programatically from the file and directory layout and content. We've handled the contents in the previous section, so now we need to handle the update in directory structure. Fortunately, this is a simple change to make.
- Open the file in the path
/docs/api.rst
from the root of the repository - Locate a line with text similar to
.. automodule:: adafruit_library
- Note: There should be only one such line, but if there are multiple, update those as well
- Update the line(s) to reflect the new directory structure, replacing the path separator, either
\/
or\\
with a period (.
)- Using the same example as above, the value
adafruit_filename
would be updated toadafruit_library.filename
- Using the same example as above, the value
After the library's been updated, the next portion which needs to be updated and not overlooked, are the examples. These are typically found in the /examples
directory, in the root of the repository. This typically involves updating the import statement(s) from something much like import adafruit_library
to the new structure similar to from adafruit_library import filename
or from adafruit_library.filename import module
This is a good place to make sure all the changes have taken, and the code still works as expected. If it all works with the updated paths and imports, this is a good place to commit your changes and save it in a good state.
Note: You should also try to generate the HTML documentation to make sure it all works as well. The instructions to do so can be found on the Creating and sharing a CircuitPython Library Learn guide, in the Sharing docs on ReadTheDocs section..
If you're adding a completely new module, which has no dependency on other modules, nothing changes. However, if you're enhancing a class with a subclass, refactoring out a base class, or need to access functionality in the other modules, follow these steps...
-
Using an import from within the same package
from . import [...]
-
Update any examples to follow the same format as in the The Follow-Through section above.
import [package_name].[library]
from [library] import [...]
tofrom [package_name].[library] import [...]
Another thing to do is to update
docs/api.rst
. Add the following for each library within the package.