From fc30a3f0bb5f7b54d60bb8714809e7959973af22 Mon Sep 17 00:00:00 2001 From: Oliver Hamlet Date: Fri, 19 Aug 2016 19:46:19 +0100 Subject: [PATCH] Replace autodoc in Sphinx With manually-written reference text. Autodoc won't work on Read The Docs because it relies on the wrapper binary to be present, and it's too complicated to build one that will work on Read The Docs and get it there. --- docs/conf.py | 1 - docs/reference.rst | 183 ++++++++++++++++++++++++++++++++++++++------- src/main.cpp | 40 +++++----- 3 files changed, 174 insertions(+), 50 deletions(-) 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(); }