diff --git a/docs/conf.py b/docs/conf.py index 10d25c2..b5971ce 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,7 +34,6 @@ sys.path.insert(0, os.path.abspath('../build/Release')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', ] diff --git a/docs/reference.rst b/docs/reference.rst index b391112..019e897 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -9,55 +9,180 @@ Enumerations ============ The wrapped enumeration types below are classes in Python, but the distinction -makes no difference in practice, so they're grouped here for semantics. +makes no difference in practice, so they're grouped here for semantics. All +values are unsigned integer constants. -.. autoclass:: loot_api.GameType - :members: - :undoc-members: +.. py:class:: loot_api.GameType -.. autoclass:: loot_api.LanguageCode - :members: - :undoc-members: + Wraps :cpp:type:`loot::GameType` to expose the LOOT API's game + codes. -.. autoclass:: loot_api.MessageType - :members: - :undoc-members: + .. py:attribute:: fo3 + .. py:attribute:: fo4 + .. py:attribute:: fonv + .. py:attribute:: tes4 + .. py:attribute:: tes5 -.. autoclass:: loot_api.PluginCleanliness - :members: - :undoc-members: +.. py:class:: loot_api.LanguageCode + + Wraps :cpp:type:`loot::LanguageCode` to expose the LOOT API's + language codes. + + .. py:attribute:: english + .. py:attribute:: spanish + .. py:attribute:: russian + .. py:attribute:: french + .. py:attribute:: chinese + .. py:attribute:: polish + .. py:attribute:: brazilian_portuguese + .. py:attribute:: finnish + .. py:attribute:: german + .. py:attribute:: danish + .. py:attribute:: korean + +.. py:class:: loot_api.MessageType + + Wraps :cpp:type:`loot::MessageType` to expose the LOOT API's + message type codes. + + .. py:attribute:: error + .. py:attribute:: say + .. py:attribute:: warn + +.. py:class:: loot_api.PluginCleanliness + + Wraps :cpp:type:`loot::PluginCleanliness` to expose the LOOT API's plugin cleanliness state codes. + + .. py:attribute:: clean + .. py:attribute:: dirty + .. py:attribute:: do_not_clean + .. py:attribute:: unknown Public-Field Data Structures ============================ Classes with public fields and no member functions. -.. autoclass:: loot_api.MasterlistInfo - :members: - :undoc-members: +.. py:class:: loot_api.MasterlistInfo -.. autoclass:: loot_api.Message - :members: - :undoc-members: + Wraps :cpp:class:`loot::MasterlistInfo`. -.. autoclass:: loot_api.PluginTags - :members: - :undoc-members: + .. py:attribute:: revision_id + + A Unicode string containing a Git commit's SHA-1 checksum. + + .. py:attribute:: revision_date + + A Unicode string containing the date of the commit given by :py:attr:`revision_id`, in ISO 8601 format (YYYY-MM-DD). + + .. py:attribute:: is_modified + + A boolean that is true if the masterlist has been modified from its state + at the commit given by :py:attr:`revision_id`. + +.. py:class:: loot_api.Message + + Wraps :cpp:class:`loot::PluginMessage`. + + .. py:attribute:: type + + A :py:class:`loot_api.MessageType` giving the message type. + + .. py:attribute:: text + + A Unicode string containing the message text. + +.. py:class:: loot_api.PluginTags + + Wraps :cpp:class:`loot::PluginTags`. + + .. py:attribute:: added + + A set of Unicode strings giving Bash Tags suggested for addition. + + .. py:attribute:: removed + + A set of Unicode strings giving Bash Tags suggested for removal. + + .. py:attribute:: is_modified + + A boolean that is true if the suggestions contain metadata obtained from a loaded userlist. Functions ========= -.. autofunction:: loot_api.is_compatible +.. py:function:: loot_api.is_compatible(int, int, int) -> bool -.. autofunction:: loot_api.create_database + Checks for API compatibility. Wraps :cpp:func:`loot::IsCompatible`. + +.. py:function:: loot_api.create_database(game : loot_api.GameType, [game_path : unicode = u'', [game_local_path : unicode = u'']]) -> loot_api.DatabaseInterface + + Initialise a new database handle. Wraps :cpp:func:`loot::IsCompatible`. Classes ======= -.. autoclass:: loot_api.DatabaseInterface - :members: +.. py:class:: loot_api.DatabaseInterface -.. autoclass:: loot_api.Version - :members: - :undoc-members: + Wraps :cpp:class:`loot::DatabaseInterface`. + + .. py:method:: eval_lists(loot_api.DatabaseInterface, loot_api.LanguageCode) -> NoneType + + Evaluates all conditions and regular expression metadata entries in the loaded metadata lists. Wraps :cpp:func:`EvalLists`. + + .. py:method:: get_masterlist_revision(loot_api.DatabaseInterface, unicode, bool) -> loot_api.MasterlistInfo + + Gets the give masterlist’s source control revision. Wraps :cpp:func:`GetMasterlistRevision`. + + .. py:method:: get_plugin_cleanliness(loot_api.DatabaseInterface, unicode) -> loot_api.PluginCleanliness + + Determines the database’s knowledge of a plugin’s cleanliness. Wraps :cpp:func:`GetPluginCleanliness`. + + .. py:method:: get_plugin_messages(loot_api.DatabaseInterface, unicode) -> list + + Outputs the messages associated with the given plugin in the database. Wraps :cpp:func:`GetPluginMessages`. + + .. py:method:: get_plugin_tags(loot_api.DatabaseInterface, unicode) -> loot_api.PluginTags + + Outputs the Bash Tags suggested for addition and removal by the database for the given plugin. Wraps :cpp:func:`GetPluginTags`. + + .. py:method:: load_lists(loot_api.DatabaseInterface, masterlist_path : unicode, [userlist_path : unicode = u'']) -> NoneType + + Loads the masterlist and userlist from the paths specified. Wraps :cpp:func:`LoadLists`. + + .. py:method:: sort_plugins(loot_api.DatabaseInterface, list) -> list + + Calculates a new load order for all a game’s installed plugins and outputs the sorted order. Wraps :cpp:func:`SortPlugins`. + + .. py:method:: update_masterlist(loot_api.DatabaseInterface, unicode, unicode, unicode) -> bool + + Updates the given masterlist using the given Git repository details. Wraps :cpp:func:`UpdateMasterlist`. + + .. py:method:: write_minimal_list(loot_api.DatabaseInterface, unicode, bool) -> NoneType + + Writes a minimal metadata file containing only Bash Tag suggestions and/or cleanliness info from the loaded metadata. Wraps :cpp:func:`WriteMinimalList`. + +.. py:class:: loot_api.Version + + Wraps :cpp:class:`loot::LootVersion`. + + .. py:attribute:: major + + An unsigned integer giving the major version number. + + .. py:attribute:: minor + + An unsigned integer giving the minor version number. + + .. py:attribute:: patch + + An unsigned integer giving the patch version number. + + .. py:attribute:: revision + + A Unicode string containing the SHA-1 of the Git revision that the wrapped C++ API was built from. + + .. py:staticmethod:: string() -> unicode + + Returns the API version as a string of the form ``major.minor.patch`` diff --git a/src/main.cpp b/src/main.cpp index 3623d78..eb9feef 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -49,14 +49,14 @@ PYBIND11_PLUGIN(loot_api) { pybind11::module module("loot_api", "A Python module that wraps the LOOT API, generated by pybind11."); - enum_(module, "GameType", "Wraps :cpp:type:`GameType `.") + enum_(module, "GameType") .value("tes4", GameType::tes4) .value("tes5", GameType::tes5) .value("fo3", GameType::fo3) .value("fonv", GameType::fonv) .value("fo4", GameType::fo4); - enum_(module, "LanguageCode", "Wraps :cpp:type:`LanguageCode `.") + enum_(module, "LanguageCode") .value("english", LanguageCode::english) .value("spanish", LanguageCode::spanish) .value("russian", LanguageCode::russian) @@ -69,52 +69,52 @@ PYBIND11_PLUGIN(loot_api) { .value("danish", LanguageCode::danish) .value("korean", LanguageCode::korean); - enum_(module, "MessageType", "Wraps :cpp:type:`MessageType `.") + enum_(module, "MessageType") .value("say", MessageType::say) .value("warn", MessageType::warn) .value("error", MessageType::error); - enum_(module, "PluginCleanliness", "Wraps :cpp:type:`Plugin Cleanliness `.") + enum_(module, "PluginCleanliness") .value("clean", PluginCleanliness::clean) .value("dirty", PluginCleanliness::dirty) .value("do_not_clean", PluginCleanliness::do_not_clean) .value("unknown", PluginCleanliness::unknown); - class_(module, "MasterlistInfo", "Wraps :cpp:class:`MasterlistInfo `.") + class_(module, "MasterlistInfo") .def_readwrite("revision_id", &MasterlistInfo::revision_id) .def_readwrite("revision_date", &MasterlistInfo::revision_date) .def_readwrite("is_modified", &MasterlistInfo::is_modified); - class_(module, "Message", "Wraps :cpp:class:`PluginMessage `.") + class_(module, "Message") .def_readwrite("type", &PluginMessage::type) .def_readwrite("text", &PluginMessage::text); - class_(module, "PluginTags", "Wraps :cpp:class:`PluginTags `.") + class_(module, "PluginTags") .def_readwrite("added", &PluginTags::added) .def_readwrite("removed", &PluginTags::removed) .def_readwrite("userlist_modified", &PluginTags::userlist_modified); - class_(module, "Version", "Wraps :cpp:class:`LootVersion `.") + class_(module, "Version") .def_readonly_static("major", &LootVersion::major) .def_readonly_static("minor", &LootVersion::minor) .def_readonly_static("patch", &LootVersion::patch) .def_readonly_static("revision", &LootVersion::revision) .def("string", LootVersion::string); - class_>(module, "DatabaseInterface", "Wraps :cpp:class:`DatabaseInterface `.") - .def("load_lists", &DatabaseInterface::LoadLists, arg("masterlist_path"), arg("userlist_path") = emptyString, "Loads the masterlist and userlist from the paths specified. Wraps :cpp:func:`LoadLists`.") - .def("eval_lists", &DatabaseInterface::EvalLists, "Evaluates all conditions and regular expression metadata entries in the loaded metadata lists. Wraps :cpp:func:`EvalLists`.") - .def("sort_plugins", &DatabaseInterface::SortPlugins, "Calculates a new load order for all a game's installed plugins and outputs the sorted order. Wraps :cpp:func:`SortPlugins`.") - .def("update_masterlist", &DatabaseInterface::UpdateMasterlist, "Updates the given masterlist using the given Git repository details. Wraps :cpp:func:`UpdateMasterlist`.") - .def("get_masterlist_revision", &DatabaseInterface::GetMasterlistRevision, "Gets the give masterlist's source control revision. Wraps :cpp:func:`GetMasterlistRevision`.") - .def("get_plugin_tags", &DatabaseInterface::GetPluginTags, "Outputs the Bash Tags suggested for addition and removal by the database for the given plugin. Wraps :cpp:func:`GetPluginTags`.") - .def("get_plugin_messages", &DatabaseInterface::GetPluginMessages, "Outputs the messages associated with the given plugin in the database. Wraps :cpp:func:`GetPluginMessages`.") - .def("get_plugin_cleanliness", &DatabaseInterface::GetPluginCleanliness, "Determines the database's knowledge of a plugin's cleanliness. Wraps :cpp:func:`GetPluginCleanliness`.") - .def("write_minimal_list", &DatabaseInterface::WriteMinimalList, "Writes a minimal metadata file containing only Bash Tag suggestions and/or cleanliness info from the loaded metadata. Wraps :cpp:func:`WriteMinimalList`."); + class_>(module, "DatabaseInterface") + .def("load_lists", &DatabaseInterface::LoadLists, arg("masterlist_path"), arg("userlist_path") = emptyString) + .def("eval_lists", &DatabaseInterface::EvalLists) + .def("sort_plugins", &DatabaseInterface::SortPlugins) + .def("update_masterlist", &DatabaseInterface::UpdateMasterlist) + .def("get_masterlist_revision", &DatabaseInterface::GetMasterlistRevision) + .def("get_plugin_tags", &DatabaseInterface::GetPluginTags) + .def("get_plugin_messages", &DatabaseInterface::GetPluginMessages) + .def("get_plugin_cleanliness", &DatabaseInterface::GetPluginCleanliness) + .def("write_minimal_list", &DatabaseInterface::WriteMinimalList); - module.def("is_compatible", &IsCompatible, "Checks for API compatibility. Wraps :cpp:func:`IsCompatible `."); + module.def("is_compatible", &IsCompatible); - module.def("create_database", &CreateDatabase, arg("game"), arg("game_path") = emptyString, arg("game_local_path") = emptyString, "Initialise a new database handle. Wraps :cpp:func:`CreateDatabase `."); + module.def("create_database", &CreateDatabase, arg("game"), arg("game_path") = emptyString, arg("game_local_path") = emptyString); return module.ptr(); }