diff --git a/docs/source/api.rst b/docs/source/api.rst deleted file mode 100644 index c8d7dd7abb..0000000000 --- a/docs/source/api.rst +++ /dev/null @@ -1,72 +0,0 @@ -Additional API features -======================= - -Sopel includes a number of additional functions that are useful for various -common IRC tasks. - -sopel.tools ------------ - -.. automodule:: sopel.tools - :members: - :exclude-members: iteritems, iterkeys, itervalues, raw_input - - -sopel.tools.identifiers ------------------------ - -.. automodule:: sopel.tools.identifiers - :members: - -sopel.tools.memories --------------------- - -.. automodule:: sopel.tools.memories - :members: - -sopel.tools.web ---------------- - -.. automodule:: sopel.tools.web - :members: - - .. autodata:: r_entity - -sopel.tools.time ----------------- -.. automodule:: sopel.tools.time - :members: - -sopel.tools.calculation ------------------------ -.. automodule:: sopel.tools.calculation - :members: - -sopel.tools.target ------------------- -.. automodule:: sopel.tools.target - :members: - -sopel.tools.events ------------------- -.. autoclass:: sopel.tools.events - :members: - :undoc-members: - -sopel.tools.jobs ----------------- -.. automodule:: sopel.tools.jobs - :members: - -sopel.formatting ----------------- -.. automodule:: sopel.formatting - :members: - :undoc-members: - -sopel.logger ------------- - -.. automodule:: sopel.logger - :members: - :undoc-members: diff --git a/docs/source/config.rst b/docs/source/config.rst deleted file mode 100644 index 1d029bc8b6..0000000000 --- a/docs/source/config.rst +++ /dev/null @@ -1,27 +0,0 @@ -=========================== -Configuration functionality -=========================== - - -sopel.config -============ - -.. automodule:: sopel.config - :members: - :undoc-members: - - -sopel.config.types -================== - -.. automodule:: sopel.config.types - :members: - :undoc-members: - - -sopel.config.core_section -========================= - -.. automodule:: sopel.config.core_section - :members: - :undoc-members: diff --git a/docs/source/irc.rst b/docs/source/irc.rst deleted file mode 100644 index b3a130e672..0000000000 --- a/docs/source/irc.rst +++ /dev/null @@ -1,59 +0,0 @@ -============ -IRC Backends -============ - -.. automodule:: sopel.irc - :no-members: - - -Bot Interface -============= - -.. autoclass:: sopel.irc.AbstractBot - :members: - :show-inheritance: - - -.. py:module:: sopel.irc.abstract_backends - -Backend Interface -================= - -.. autoclass:: sopel.irc.abstract_backends.AbstractIRCBackend - :members: - - -.. py:module:: sopel.irc.backends - -Backends -======== - -.. autoclass:: sopel.irc.backends.AsynchatBackend - :members: - :show-inheritance: - - -.. autoclass:: sopel.irc.backends.SSLAsynchatBackend - :members: - :show-inheritance: - - -Mode Messages -============= - -.. automodule:: sopel.irc.modes - :members: - - -ISUPPORT -======== - -.. automodule:: sopel.irc.isupport - :members: - - -Utility -======= - -.. automodule:: sopel.irc.utils - :members: diff --git a/docs/source/package.rst b/docs/source/package.rst index 721c5af373..fa3700279d 100644 --- a/docs/source/package.rst +++ b/docs/source/package.rst @@ -5,10 +5,13 @@ Sopel Package API .. toctree:: :titlesonly: - bot - trigger - config - db - api - irc - lifecycle + package/bot + package/trigger + package/config + package/db + package/tools + package/formatting + package/logger + package/irc + package/plugins + package/lifecycle diff --git a/docs/source/bot.rst b/docs/source/package/bot.rst similarity index 60% rename from docs/source/bot.rst rename to docs/source/package/bot.rst index b20d9a89d7..1382341d1e 100644 --- a/docs/source/bot.rst +++ b/docs/source/package/bot.rst @@ -2,10 +2,7 @@ The bot and its state ===================== -.. autoclass:: sopel.bot.Sopel +.. automodule:: sopel.bot :members: :inherited-members: :show-inheritance: - -.. autoclass:: sopel.bot.SopelWrapper - :members: diff --git a/docs/source/package/config.rst b/docs/source/package/config.rst new file mode 100644 index 0000000000..452848e0d6 --- /dev/null +++ b/docs/source/package/config.rst @@ -0,0 +1,15 @@ +=========================== +Configuration functionality +=========================== + +.. toctree:: + + config/types + config/core_section + +sopel.config +============ + +.. automodule:: sopel.config + :members: + :undoc-members: diff --git a/docs/source/package/config/core_section.rst b/docs/source/package/config/core_section.rst new file mode 100644 index 0000000000..8591f9e54b --- /dev/null +++ b/docs/source/package/config/core_section.rst @@ -0,0 +1,7 @@ +============ +Core Section +============ + +.. automodule:: sopel.config.core_section + :members: + :undoc-members: diff --git a/docs/source/package/config/types.rst b/docs/source/package/config/types.rst new file mode 100644 index 0000000000..d142876e45 --- /dev/null +++ b/docs/source/package/config/types.rst @@ -0,0 +1,7 @@ +============ +Option Types +============ + +.. automodule:: sopel.config.types + :members: + :undoc-members: diff --git a/docs/source/db.rst b/docs/source/package/db.rst similarity index 100% rename from docs/source/db.rst rename to docs/source/package/db.rst diff --git a/docs/source/package/formatting.rst b/docs/source/package/formatting.rst new file mode 100644 index 0000000000..16daebf950 --- /dev/null +++ b/docs/source/package/formatting.rst @@ -0,0 +1,7 @@ +========== +Formatting +========== + +.. automodule:: sopel.formatting + :members: + :undoc-members: diff --git a/docs/source/package/irc.rst b/docs/source/package/irc.rst new file mode 100644 index 0000000000..df2aa34ab3 --- /dev/null +++ b/docs/source/package/irc.rst @@ -0,0 +1,20 @@ +======================= +IRC Core Implementation +======================= + +.. toctree:: + + irc/backends + irc/modes + irc/isupport + irc/utils + +.. automodule:: sopel.irc + :members: + :undoc-members: + :inherited-members: + :show-inheritance: + + .. autoclass:: AbstractBot + :members: + :undoc-members: diff --git a/docs/source/package/irc/backends.rst b/docs/source/package/irc/backends.rst new file mode 100644 index 0000000000..7b5944834c --- /dev/null +++ b/docs/source/package/irc/backends.rst @@ -0,0 +1,17 @@ +============ +IRC Backends +============ + +sopel.irc.abstract_backends +=========================== + +.. automodule:: sopel.irc.abstract_backends + :members: + + +sopel.irc.backends +================== + +.. automodule:: sopel.irc.backends + :members: + :show-inheritance: diff --git a/docs/source/package/irc/isupport.rst b/docs/source/package/irc/isupport.rst new file mode 100644 index 0000000000..0d3e084051 --- /dev/null +++ b/docs/source/package/irc/isupport.rst @@ -0,0 +1,6 @@ +======== +ISUPPORT +======== + +.. automodule:: sopel.irc.isupport + :members: diff --git a/docs/source/package/irc/modes.rst b/docs/source/package/irc/modes.rst new file mode 100644 index 0000000000..a28dcaa31c --- /dev/null +++ b/docs/source/package/irc/modes.rst @@ -0,0 +1,6 @@ +============= +Mode Messages +============= + +.. automodule:: sopel.irc.modes + :members: diff --git a/docs/source/package/irc/utils.rst b/docs/source/package/irc/utils.rst new file mode 100644 index 0000000000..5387a58932 --- /dev/null +++ b/docs/source/package/irc/utils.rst @@ -0,0 +1,6 @@ +======= +Utility +======= + +.. automodule:: sopel.irc.utils + :members: diff --git a/docs/source/lifecycle.rst b/docs/source/package/lifecycle.rst similarity index 100% rename from docs/source/lifecycle.rst rename to docs/source/package/lifecycle.rst diff --git a/docs/source/package/loader.rst b/docs/source/package/loader.rst new file mode 100644 index 0000000000..1699f33cf3 --- /dev/null +++ b/docs/source/package/loader.rst @@ -0,0 +1,6 @@ +============= +Plugin Loader +============= + +.. automodule:: sopel.loader + :members: diff --git a/docs/source/package/logger.rst b/docs/source/package/logger.rst new file mode 100644 index 0000000000..49121f712e --- /dev/null +++ b/docs/source/package/logger.rst @@ -0,0 +1,7 @@ +====== +Logger +====== + +.. automodule:: sopel.logger + :members: + :undoc-members: diff --git a/docs/source/package/plugins.rst b/docs/source/package/plugins.rst new file mode 100644 index 0000000000..a45598b9ee --- /dev/null +++ b/docs/source/package/plugins.rst @@ -0,0 +1,18 @@ +========================= +Plugin Internal Machinery +========================= + +.. important:: + + This section contains modules and classes used by Sopel internally. They are + subject to rapid changes between versions, without advance warning. This + section exists primarily for the aid of Sopel’s core development. + +.. toctree:: + + loader + plugins/plugins + plugins/exceptions + plugins/handlers + plugins/jobs + plugins/rules diff --git a/docs/source/package/plugins/exceptions.rst b/docs/source/package/plugins/exceptions.rst new file mode 100644 index 0000000000..e4cb6419de --- /dev/null +++ b/docs/source/package/plugins/exceptions.rst @@ -0,0 +1,6 @@ +======================== +sopel.plugins.exceptions +======================== + +.. automodule:: sopel.plugins.exceptions + :members: diff --git a/docs/source/package/plugins/handlers.rst b/docs/source/package/plugins/handlers.rst new file mode 100644 index 0000000000..e5a94ce3e0 --- /dev/null +++ b/docs/source/package/plugins/handlers.rst @@ -0,0 +1,6 @@ +====================== +sopel.plugins.handlers +====================== + +.. automodule:: sopel.plugins.handlers + :members: diff --git a/docs/source/package/plugins/jobs.rst b/docs/source/package/plugins/jobs.rst new file mode 100644 index 0000000000..eaa20407ac --- /dev/null +++ b/docs/source/package/plugins/jobs.rst @@ -0,0 +1,7 @@ +================== +sopel.plugins.jobs +================== + +.. automodule:: sopel.plugins.jobs + :members: + :show-inheritance: diff --git a/docs/source/package/plugins/plugins.rst b/docs/source/package/plugins/plugins.rst new file mode 100644 index 0000000000..8f0e7fb036 --- /dev/null +++ b/docs/source/package/plugins/plugins.rst @@ -0,0 +1,6 @@ +============= +sopel.plugins +============= + +.. automodule:: sopel.plugins + :members: diff --git a/docs/source/plugin/internals.rst b/docs/source/package/plugins/rules.rst similarity index 51% rename from docs/source/plugin/internals.rst rename to docs/source/package/plugins/rules.rst index 8cc4816e81..a3ffea267c 100644 --- a/docs/source/plugin/internals.rst +++ b/docs/source/package/plugins/rules.rst @@ -1,45 +1,4 @@ -================== -Internal machinery -================== - -.. important:: - - This section contains modules and classes used by Sopel internally. They are - subject to rapid changes between versions. They are documented here for - completeness, and for the aid of Sopel’s core development. - - -sopel.loader -============ - -.. automodule:: sopel.loader - :members: - -sopel.plugins -============= - -.. automodule:: sopel.plugins - :members: - -sopel.plugins.exceptions -======================== - -.. automodule:: sopel.plugins.exceptions - :members: - -sopel.plugins.handlers -====================== - -.. automodule:: sopel.plugins.handlers - :members: - -sopel.plugins.jobs -================== - -.. automodule:: sopel.plugins.jobs - :members: - :show-inheritance: - +=================== sopel.plugins.rules =================== diff --git a/docs/source/package/tools.rst b/docs/source/package/tools.rst new file mode 100644 index 0000000000..660c5c92a3 --- /dev/null +++ b/docs/source/package/tools.rst @@ -0,0 +1,22 @@ +================ +Additional Tools +================ + +.. toctree:: + + tools/calculation + tools/events + tools/identifiers + tools/jobs + tools/memories + tools/target + tools/time + tools/web + + +sopel.tools +=========== + +.. automodule:: sopel.tools + :members: + :exclude-members: iteritems, iterkeys, itervalues, raw_input diff --git a/docs/source/package/tools/calculation.rst b/docs/source/package/tools/calculation.rst new file mode 100644 index 0000000000..0bd2392a86 --- /dev/null +++ b/docs/source/package/tools/calculation.rst @@ -0,0 +1,6 @@ +======================= +sopel.tools.calculation +======================= + +.. automodule:: sopel.tools.calculation + :members: diff --git a/docs/source/package/tools/events.rst b/docs/source/package/tools/events.rst new file mode 100644 index 0000000000..56d37c152d --- /dev/null +++ b/docs/source/package/tools/events.rst @@ -0,0 +1,7 @@ +================== +sopel.tools.events +================== + +.. autoclass:: sopel.tools.events + :members: + :undoc-members: diff --git a/docs/source/package/tools/identifiers.rst b/docs/source/package/tools/identifiers.rst new file mode 100644 index 0000000000..d43f866ef3 --- /dev/null +++ b/docs/source/package/tools/identifiers.rst @@ -0,0 +1,6 @@ +======================= +sopel.tools.identifiers +======================= + +.. automodule:: sopel.tools.identifiers + :members: diff --git a/docs/source/package/tools/jobs.rst b/docs/source/package/tools/jobs.rst new file mode 100644 index 0000000000..b346d6d2c9 --- /dev/null +++ b/docs/source/package/tools/jobs.rst @@ -0,0 +1,6 @@ +================ +sopel.tools.jobs +================ + +.. automodule:: sopel.tools.jobs + :members: diff --git a/docs/source/package/tools/memories.rst b/docs/source/package/tools/memories.rst new file mode 100644 index 0000000000..5906afdee3 --- /dev/null +++ b/docs/source/package/tools/memories.rst @@ -0,0 +1,6 @@ +==================== +sopel.tools.memories +==================== + +.. automodule:: sopel.tools.memories + :members: diff --git a/docs/source/package/tools/target.rst b/docs/source/package/tools/target.rst new file mode 100644 index 0000000000..01c5a05939 --- /dev/null +++ b/docs/source/package/tools/target.rst @@ -0,0 +1,6 @@ +================== +sopel.tools.target +================== + +.. automodule:: sopel.tools.target + :members: diff --git a/docs/source/package/tools/time.rst b/docs/source/package/tools/time.rst new file mode 100644 index 0000000000..86ea59c325 --- /dev/null +++ b/docs/source/package/tools/time.rst @@ -0,0 +1,6 @@ +================ +sopel.tools.time +================ + +.. automodule:: sopel.tools.time + :members: diff --git a/docs/source/package/tools/web.rst b/docs/source/package/tools/web.rst new file mode 100644 index 0000000000..c4f8b6311c --- /dev/null +++ b/docs/source/package/tools/web.rst @@ -0,0 +1,8 @@ +=============== +sopel.tools.web +=============== + +.. automodule:: sopel.tools.web + :members: + + .. autodata:: r_entity diff --git a/docs/source/package/trigger.rst b/docs/source/package/trigger.rst new file mode 100644 index 0000000000..86002d0e1d --- /dev/null +++ b/docs/source/package/trigger.rst @@ -0,0 +1,6 @@ +======== +Triggers +======== + +.. automodule:: sopel.trigger + :members: diff --git a/docs/source/plugin.rst b/docs/source/plugin.rst index fbbf60486d..44847c954f 100644 --- a/docs/source/plugin.rst +++ b/docs/source/plugin.rst @@ -13,7 +13,6 @@ Plugins: Developer Overview plugin/decorators plugin/test plugin/advanced - plugin/internals Plugin glossary =============== diff --git a/docs/source/tests.rst b/docs/source/tests.rst index e6f7b9a0e6..4e0e52624f 100644 --- a/docs/source/tests.rst +++ b/docs/source/tests.rst @@ -2,29 +2,11 @@ Testing tools ============= +.. toctree:: -Common tools -============ + tests/pytest + tests/factories + tests/mocks .. automodule:: sopel.tests :members: - -Fixtures with py.test -===================== - -.. automodule:: sopel.tests.pytest_plugin - :members: - - -Factories -========= - -.. automodule:: sopel.tests.factories - :members: - - -Mocks -===== - -.. automodule:: sopel.tests.mocks - :members: diff --git a/docs/source/tests/factories.rst b/docs/source/tests/factories.rst new file mode 100644 index 0000000000..a79b5b4f80 --- /dev/null +++ b/docs/source/tests/factories.rst @@ -0,0 +1,6 @@ +========= +Factories +========= + +.. automodule:: sopel.tests.factories + :members: diff --git a/docs/source/tests/mocks.rst b/docs/source/tests/mocks.rst new file mode 100644 index 0000000000..ab61782c9d --- /dev/null +++ b/docs/source/tests/mocks.rst @@ -0,0 +1,6 @@ +===== +Mocks +===== + +.. automodule:: sopel.tests.mocks + :members: diff --git a/docs/source/tests/pytest.rst b/docs/source/tests/pytest.rst new file mode 100644 index 0000000000..200f675735 --- /dev/null +++ b/docs/source/tests/pytest.rst @@ -0,0 +1,6 @@ +==================== +Fixtures with pytest +==================== + +.. automodule:: sopel.tests.pytest_plugin + :members: diff --git a/docs/source/trigger.rst b/docs/source/trigger.rst deleted file mode 100644 index 9f2c356760..0000000000 --- a/docs/source/trigger.rst +++ /dev/null @@ -1,15 +0,0 @@ -Triggers -======== - -A :class:`~.trigger.Trigger` is the main type of user input plugins will see. - -Sopel uses :class:`~.trigger.PreTrigger`\s internally while processing -incoming IRC messages. Plugin authors can reasonably expect that their code -will never receive one. They are documented here for completeness, and for the -aid of Sopel's core development. - -.. autoclass:: sopel.trigger.Trigger - :members: - -.. autoclass:: sopel.trigger.PreTrigger - :members: diff --git a/sopel/trigger.py b/sopel/trigger.py index d5dafb6034..35ecc8f3a4 100644 --- a/sopel/trigger.py +++ b/sopel/trigger.py @@ -1,4 +1,12 @@ -"""Triggers are how Sopel tells callables about their runtime context.""" +"""Triggers are how Sopel tells callables about their runtime context. + +A :class:`~.trigger.Trigger` is the main type of user input plugins will see. + +Sopel uses :class:`~.trigger.PreTrigger`\\s internally while processing +incoming IRC messages. Plugin authors can reasonably expect that their code +will never receive one. They are documented here for completeness, and for the +aid of Sopel's core development. +""" from __future__ import annotations import datetime