io: Use init file to define inclusion in public API

Broad inclusion of everything at the augur.io level can lead to indirect imports from internal code, which is why the previous commit removed those. However, it is necessary to expose some functions at the top level so API users do not have to use direct imports (e.g. from augur.io.metadata import read_metadata). Instead of defining the members of the public API in both the init file and the docs page, just define them in the init file and include all imported members in the docs page.
nextstrain · Nov 7, 2022 · bfdf551 · bfdf551
1 parent 8c7e759
commit bfdf551
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 1 deletion.
diff --git a/augur/io/__init__.py b/augur/io/__init__.py
@@ -1,2 +1,6 @@
 """Interfaces for reading and writing data also known as input/output (I/O)
 """
+# Functions and variables exposed here are part of Augur's public Python API.
+# To use functions internally, import directly from the submodule.
+from .metadata import read_metadata
+from .sequences import read_sequences
diff --git a/docs/api/public/augur.io.rst b/docs/api/public/augur.io.rst
@@ -1,7 +1,10 @@
 augur.io
 ========
 
+.. The public API portion of augur.io is everything that is exposed by io/__init__.py.
+
 .. automodule:: augur.io
-   :members: read_metadata, read_sequences
+   :members:
+   :imported-members:
    :undoc-members:
    :show-inheritance: