diff --git a/cmake_modules/default_sphinx_configuration/conf.py b/cmake_modules/default_sphinx_configuration/conf.py new file mode 100644 index 0000000..0b7f867 --- /dev/null +++ b/cmake_modules/default_sphinx_configuration/conf.py @@ -0,0 +1,97 @@ +import sphinx.util.docutils +import sphinx.util.logging +import pygments.lexers.c_cpp +import sphinx.highlighting + +from pathlib import Path + +# TODO instead of trying to provide defaults for config settings, +# let the maud extension just assert that config doesn't have any errors +# (like failure to exclude CMAKE_SOURCE_DIR). +import maud + +logger = sphinx.util.logging.getLogger(__name__) + +project = maud.cache.PROJECT_NAME +extensions = ["maud", "trike"] +templates_path = [] +exclude_patterns = ["CMAKE_SOURCE_DIR", "Thumbs.db", ".DS_Store"] +html_static_path = [] +source_suffix = { + ".rst": "restructuredtext", +} + +author = "Benjamin Kietzman " + +html_title = "Maud" +html_theme = "furo" +html_theme_options = { + "footer_icons": [ + { + "name": "GitHub", + "url": "https://github.com/bkietz/maud", + "html": """ + + + + """, + "class": "", + }, + ], + "top_of_page_buttons": ["view", "edit"], + "navigation_with_keys": True, + "source_repository": "https://github.com/bkietz/maud/", + "source_branch": "trunk", + "source_directory": "", +} +html_context = { + "github_user": "bkietz", + "github_repo": "maud", + "github_version": "trunk", + "doc_path": "", +} + +pygments_style = "default" +pygments_dark_style = "monokai" + +extensions += ["sphinx.ext.autosectionlabel"] +autosectionlabel_maxdepth = 2 +autosectionlabel_prefix_document = True + +extensions += ["sphinx.ext.duration"] +extensions += ["sphinx_inline_tabs"] + +extensions += ["sphinx.ext.extlinks"] +extlinks_detect_hardcoded_links = True +extlinks = { + "cxx20": ("https://timsong-cpp.github.io/cppwp/n4868/%s", "C++20:%s"), + # TODO this should be intersphinx instead + "cmake": ("https://cmake.org/cmake/help/latest/%s", None), + "mastering-cmake": ("https://cmake.org/cmake/help/book/mastering-cmake/chapter/%s", None), + "gtest": ("https://google.github.io/googletest/%s", None), + "sphinx": ("https://www.sphinx-doc.org/en/master/usage/%s", None), +} + +trike_files = [ + *maud.cache.CMAKE_SOURCE_DIR.glob("*.cxx"), + *maud.cache.CMAKE_SOURCE_DIR.glob("cmake_modules/*.cxx"), + *maud.cache.CMAKE_SOURCE_DIR.glob("cmake_modules/*.hxx"), +] +# FIXME with c++20 libclang parses exported decls to UNEXPOSED_DECL +trike_clang_args = ["-std=gnu++20", "-Dexport="] + + +def trike_get_uri(file, line): + # FIXME what if file was generated? + relative = file.relative_to(maud.cache.CMAKE_SOURCE_DIR) + return f"https://github.com/bkietz/maud/blob/trunk/{relative}#L{line}" + + +def setup(app): + sphinx.highlighting.lexers["c++.in2"] = pygments.lexers.c_cpp.CppLexer() + # def lexer(*args, **kwargs): + # print(args, kwargs) + # return pygments.lexers.c_cpp.CppLexer(*args, **kwargs) + # app.add_lexer("c++.in2", lexer) + # TODO make a utility for building in2 lexers and embed cmake's syntax + # https://pygments.org/docs/lexerdevelopment/#using-multiple-lexers diff --git a/cmake_modules/test_.cxx b/cmake_modules/test_.cxx index e10d92c..4b88119 100644 --- a/cmake_modules/test_.cxx +++ b/cmake_modules/test_.cxx @@ -15,16 +15,27 @@ export import :main; using namespace testing; +///.. cpp:var:: template std::string const type_name +/// +/// A string representation of a type's name. +/// +/// By default this is a best effort demangling from type_info. +/// This template can be specialized to override the default string. +/// +/// .. code-block:: +/// +/// template <> +/// std::string const type_name> = "Selection"; export template std::string const type_name = testing::internal::GetTypeName(); export using testing::PrintToString; export template <> -auto const type_name = "std::string"; +std::string const type_name = "std::string"; export template <> -auto const type_name = "std::string_view"; +std::string const type_name = "std::string_view"; export struct Main { Main(int &argc, char **argv) { InitGoogleTest(&argc, argv); } @@ -421,7 +432,11 @@ struct DefaultDescription { /// }}; /// } /// -/// Description of the matcher can be cusotmized with another lambda: +/// On failed expectations, matchers output a description of the way +/// matching failed. By default, this uses the :var:`type_name\` of +/// the match lambda (which is usually something unique but uninformative, +/// like ``"$_1"``). +/// Description of the matcher can be customized with another lambda: /// /// .. code-block:: /// @@ -429,7 +444,7 @@ struct DefaultDescription { /// return Matcher{ /// .match = [=](Foo f, std::ostream &os) { return f.bar() + f.baz() == n; }, /// .description = [=](std::ostream &os, bool negated) { -/// os << "bar() + baz() "; +/// os << "bar() + baz()"; /// os << (negated ? " does not equal " : " equals ") << n; /// }, /// }; diff --git a/cmake_modules/trike/README.rst b/cmake_modules/trike/README.rst index c3f3283..2efc2aa 100644 --- a/cmake_modules/trike/README.rst +++ b/cmake_modules/trike/README.rst @@ -139,9 +139,9 @@ base class from documentation: .. code-block:: c++ - ///.. cpp:class:: template Stream + ///.. cpp:class:: template Stream template - class Stream : impl::StreamMixin + class Stream : impl::StreamMixin ... that base class doesn't appear in the explicit directive, so sphinx will never know about it. diff --git a/testing.rst b/testing.rst index c0c01e9..9eb07e8 100644 --- a/testing.rst +++ b/testing.rst @@ -76,6 +76,8 @@ Unit test API typename Description = DefaultDescription> \ Matcher +.. trike-var:: template std::string const type_name + .. TODO document Main or whatever helper, setting up state in main() Custom ``main()``