From 8931fe59546914b8c9175bf56f96a6f375739f60 Mon Sep 17 00:00:00 2001 From: Isabella Muerte Date: Thu, 1 Dec 2016 13:52:48 -0800 Subject: [PATCH] [skip ci] Starting to update documentation. Switch to the absolutely wonderful "guzzle" theme for sphinx. Deleted the old custom theme. Starting move to the newer syntax used by sphinx for c++ template classes. Resolve a few formatting issues. Starting to update mentions of the never release 1.2 to the upcoming 2.0 release. --- Readme.rst | 12 +-- docs/conf.py | 16 ++-- docs/functional.rst | 147 +++++++++++++++------------------ docs/index.rst | 2 +- docs/static/theme.css | 45 ---------- docs/templates/layout.html | 12 --- docs/templates/navigation.html | 4 - docs/type-traits.rst | 45 +++++----- docs/usage.rst | 85 +++++++++---------- 9 files changed, 148 insertions(+), 220 deletions(-) delete mode 100644 docs/static/theme.css delete mode 100644 docs/templates/layout.html delete mode 100644 docs/templates/navigation.html diff --git a/Readme.rst b/Readme.rst index 0c26ed2..0ddea16 100644 --- a/Readme.rst +++ b/Readme.rst @@ -13,10 +13,10 @@ Build scripts provided by MNMLSTC Core are released under the CC0 1.0 Universal License. .. image:: https://travis-ci.org/mnmlstc/core.svg - :target: https://travis-ci.org/mnmlstc/core + :target: https://travis-ci.org/mnmlstc/core .. image:: https://codecov.io/gh/mnmlstc/core/branch/master/graph/badge.svg - :target: https://codecov.io/gh/mnmlstc/core + :target: https://codecov.io/gh/mnmlstc/core Components ---------- @@ -46,13 +46,13 @@ There are several requirements to fully use MNMLSTC Core: set required to build and use MNMLSTC Core) * `CMake 3.0.0 `_ -Additionally, to actively develop MNMLSTC Core, the following are required: +Additionally, to develop or package MNMLSTC Core, the following are required: * `Sphinx Documentation Generator `_ - * `Alabaster Sphinx Theme `_ + * `Guzzle Sphinx Theme `_ * `WiX Toolset `_ -Sphinx and the Alabaster Sphinx Theme are only necessary if generating -documentation manually. +Sphinx and the Guzzle Sphinx Theme are only necessary if generating +documentation manually to be included with the package. WiX Toolset is only required if building packages for Windows. diff --git a/docs/conf.py b/docs/conf.py index 383cdf4..aad03b5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -import alabaster as theme +import guzzle_sphinx_theme import os project = 'MNMLSTC Core' @@ -10,12 +10,10 @@ needs_sphinx = '1.3' -html_static_path = ['static'] -html_theme_path = [theme.get_path()] -html_theme = 'alabaster' -html_theme_options = { 'show_powered_by' : False } -html_style = 'theme.css' -html_sidebars = { '**' : ['navigation.html'] } +html_translate_class = 'guzzle_sphinx_theme.HTMLTranslator' +html_theme_path = guzzle_sphinx_theme.html_theme_path() +html_theme = 'guzzle_sphinx_theme' +html_theme_options = dict(project_nav_name='MNMLSTC Core') highlight_language = 'cpp' primary_domain = 'cpp' @@ -23,7 +21,7 @@ pygments_style = 'manni' exclude_patterns = ['_build'] -templates_path = ['templates'] +#templates_path = ['templates'] source_suffix = '.rst' master_doc = 'index' @@ -36,6 +34,6 @@ ''' -extensions = ['sphinx.ext.todo', 'alabaster'] +extensions = ['sphinx.ext.todo']#, 'guzzle_sphinx_theme'] todo_include_todos = True diff --git a/docs/functional.rst b/docs/functional.rst index e6766a8..7697f9c 100644 --- a/docs/functional.rst +++ b/docs/functional.rst @@ -18,7 +18,7 @@ header. .. class:: unpack_t - .. deprecated:: 1.2 Use :any:`apply` instead of invoke and unpack. + .. deprecated:: 2.0 Use :any:`apply` instead of invoke and unpack. A sentinel class to represent that one wishes to call :any:`invoke` with unpack semantics. An instance is available under the name :samp:`{unpack}`. @@ -29,12 +29,12 @@ header. runtime unpack semantics. An instance is available under the name :samp:`{runpack}`. -.. class:: is_reference_wrapper +.. class:: template is_reference_wrapper A type trait that will be :cxx:`std::true_type` if :samp:`{T}` is some form of :cxx:`std::reference_wrapper`. -.. class:: function_traits +.. class:: template function_traits Function traits to discern various amounts of details for a given callable type :samp:`{T}`. The traits allow one to get the :member:`arity` of a @@ -50,21 +50,20 @@ header. .. member:: static constexpr size_t arity - :type: :cxx:`std::size_t` - Represents the number of arguments the callable :samp:`{T}` takes. - .. type:: argument + .. type:: template argument Given a :cxx:`std::size_t` :samp:`{N}`, argument will be a type alias for the type located at the index in its parameter list. -.. function:: auto invoke (Functor&& f, Args&&...) +.. function:: template \ + auto invoke (Functor&& f, Args&&...) An implemenetation of the *INVOKE* pseudo-expression as defined in the C++11 standard. - .. versionchanged:: 1.2 There are now only two overloads for this function + .. versionchanged:: 2.0 There are now only two overloads for this function that now encompass the previous versions, while also augmenting their use (:cxx:`std::reference_wrapper` and smart pointers are now guaranteed to be usable as the 'object' parameter when invoking a member function @@ -84,16 +83,18 @@ header. assert(core::invoke(mem_fn, ptr) == 13); assert(core::invoke(mem_fn, ref) == 13); -.. function:: auto apply (Functor&& f, Tuple&& t) +.. function:: template \ + auto apply (Functor&& f, Tuple&& t) - .. versionadded:: 1.2 + .. versionadded:: 2.0 Unpacks the elements of :samp:`{t}` into :samp:`{f}` and then invokes :samp:`{f}`. -.. function:: apply_functor make_apply(F&& f) +.. function:: template \ + apply_functor make_apply(F&& f) - .. versionadded:: 1.2 + .. versionadded:: 2.0 Creates an :any:`apply_functor` via template deduction. @@ -117,24 +118,24 @@ objects: static constexpr auto less = core::less<> { }; static_assert(less(3, 4), ""); -.. class:: apply_functor +.. class:: template apply_functor - .. versionadded:: 1.2 + .. versionadded:: 2.0 A functor type that allows :any:`apply` to be used in conjunction with the standard library algorithm functions. :example: - .. code-block:: cpp + .. code-block:: cpp - std::vector> x; - auto f = make_apply([] (std::string, int, double) { }); - for_each(core, f); + std::vector> x; + auto f = make_apply([] (std::string, int, double) { }); + for_each(core, f); -.. class:: converter +.. class:: template converter - .. versionadded:: 1.2 + .. versionadded:: 2.0 A functor type that allows construction of a :samp:`{T}` from any other type. This is most useful for calls to :any:`transform`, when a @@ -149,38 +150,32 @@ objects: :example: - .. code-block:: cpp + .. code-block:: cpp - using duration = std::chrono::seconds; - std::vector ints { 1, 2, 3, 4, 5 }; - std::vector secs { }; - auto inserter = std::back_inserter(secs); - core::transform(ints, secs, converter { }); + using duration = std::chrono::seconds; + std::vector ints { 1, 2, 3, 4, 5 }; + std::vector secs { }; + auto inserter = std::back_inserter(secs); + core::transform(ints, secs, converter { }); Arithmetic Function Objects ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. class:: plus +.. class:: template plus - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator +` on two instances of type :samp:`{T}`. - .. type:: result_type - first_argument_type - second_argument_type - - Represents :samp:`{T}` - .. function:: constexpr T operator () (T const& lhs, T const& rhs) const Calls :cxx:`operator +` on :samp:`{lhs}` and :samp:`{rhs}` and returns the result. -.. class:: plus +.. class:: template <> plus - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -189,26 +184,20 @@ Arithmetic Function Objects Calls :cxx:`operator +` via template deduction on :samp:`{lhs}` and :samp:`{rhs}` and returns the result. -.. class:: minus +.. class:: template minus - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator -` on two instances of type :samp:`{T}`. - .. type:: result_type - first_argument_type - second_argument_type - - Represents :samp:`{T}` - .. function:: constexpr T operator () (T const& lhs, T const& rhs) const Calls :cxx:`operator -` on :samp:`{lhs}` and :samp:`{rhs}` and returns the result. -.. class:: minus +.. class:: template <> minus - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -219,7 +208,7 @@ Arithmetic Function Objects .. class:: multiplies - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator*` on two instances of type :samp:`{T}`. @@ -236,7 +225,7 @@ Arithmetic Function Objects .. class:: multiplies - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -247,7 +236,7 @@ Arithmetic Function Objects .. class:: divides - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator /` on two instances of type :samp:`{T}`. @@ -264,7 +253,7 @@ Arithmetic Function Objects .. class:: divides - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -275,7 +264,7 @@ Arithmetic Function Objects .. class:: modulus - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call ``operator %`` on two instances of :samp:`{T}`. @@ -292,7 +281,7 @@ Arithmetic Function Objects .. class:: modulus - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -306,7 +295,7 @@ Comparison Function Objects .. class:: equal_to - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator ==` on two instances of :samp:`{T}`. @@ -326,7 +315,7 @@ Comparison Function Objects .. class:: equal_to - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -337,7 +326,7 @@ Comparison Function Objects .. class:: not_equal_to - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator !=` on two instances of :samp:`{T}`. @@ -357,7 +346,7 @@ Comparison Function Objects .. class:: not_equal_to - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -368,7 +357,7 @@ Comparison Function Objects .. class:: greater_equal - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator >=` on two instances of :samp:`{T}`. @@ -388,7 +377,7 @@ Comparison Function Objects .. class:: greater_equal - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -399,7 +388,7 @@ Comparison Function Objects .. class:: less_equal - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator <=` on two instances of :samp:`{T}`. @@ -419,7 +408,7 @@ Comparison Function Objects .. class:: less_equal - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -430,7 +419,7 @@ Comparison Function Objects .. class:: greater - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator >` on two instances of :samp:`{T}`. @@ -450,7 +439,7 @@ Comparison Function Objects .. class:: greater - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -461,7 +450,7 @@ Comparison Function Objects .. class:: less - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator <` on two instances of :samp:`{T}`. @@ -481,7 +470,7 @@ Comparison Function Objects .. class:: less - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -495,7 +484,7 @@ Logical Function Objects .. class:: logical_and - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator and` on two instances of :samp:`{T}`. @@ -515,7 +504,7 @@ Logical Function Objects .. class:: logical_and - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -526,7 +515,7 @@ Logical Function Objects .. class:: logical_or - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator or` on two instances of :samp:`{T}`. @@ -546,7 +535,7 @@ Logical Function Objects .. class:: logical_or - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -557,7 +546,7 @@ Logical Function Objects .. class:: logical_not - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator not` on an instance of :samp:`{T}`. @@ -575,7 +564,7 @@ Logical Function Objects .. class:: logic_not - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -588,7 +577,7 @@ Bitwise Function Objects .. class:: bit_and - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator &` on two instances of :samp:`{T}`. @@ -605,7 +594,7 @@ Bitwise Function Objects .. class:: bit_and - .. version::added:: 1.2 + .. version::added:: 2.0 .. type:: is_transparent @@ -616,7 +605,7 @@ Bitwise Function Objects .. class:: bit_xor - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator ^` on two instances of :samp:`{T}`. @@ -633,7 +622,7 @@ Bitwise Function Objects .. class:: bit_xor - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -644,7 +633,7 @@ Bitwise Function Objects .. class:: bit_or - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator|` on two instances of :samp:`{T}`. @@ -661,7 +650,7 @@ Bitwise Function Objects .. class:: bit_or - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -672,7 +661,7 @@ Bitwise Function Objects .. class:: bit_not - .. versionadded:: 1.2 + .. versionadded:: 2.0 Used to call :cxx:`operator ~` on one instance of :samp:`{T}`. @@ -687,7 +676,7 @@ Bitwise Function Objects .. class:: bit_not - .. versionadded:: 1.2 + .. versionadded:: 2.0 .. type:: is_transparent @@ -705,7 +694,7 @@ version of Core. .. function:: auto invoke (unpack_t, Functor&& f, Unpackable&& u) auto invoke (unpack_t, Unpackable&& u) - :deprecated: 1.2 Use :func:`apply` instead. + :deprecated: 2.0 Use :func:`apply` instead. .. function:: auto invoke (runpack_t, Functor&& f, Runpackable&& r) diff --git a/docs/index.rst b/docs/index.rst index 63ffcb0..c06fc9a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,7 +15,7 @@ glance at the :ref:`Generated Index` might be of assistance. A :ref:`search` feature is also available. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :hidden: Using MNMLSTC Core diff --git a/docs/static/theme.css b/docs/static/theme.css deleted file mode 100644 index 8ca43a4..0000000 --- a/docs/static/theme.css +++ /dev/null @@ -1,45 +0,0 @@ -@import url("alabaster.css"); -@import url("pygments.css"); -@import url(http://fonts.googleapis.com/css?family=Maven+Pro|Raleway); - -div[class^='highlight'] pre { - font-size:16px; - font-family:"Consolas", "Liberation Mono", "Menlo", "Courier", "monospace"; - background-color: #FFF; - margin-left: 0px; - margin-top: 0px; - margin-bottom: 0px; - padding-left: 0px; -} - -div.linenodiv pre { margin-top: 0px; margin-bottom: 0px; padding-left: 0px; } - -code, .rst-content tt { - font-family:"Consolas", "Liberation Mono", "Menlo", "Courier", "monospace"; -} - -table.highlighttable { - margin-left: 0px; - margin-bottom: 2em; - border: 1px solid #ccc; -} - -dt { font-size:16px !important; width:100%; border-top-width:0px !important; } -dt:target, .highlight { background-color: #FBE54E; } - -code.descname { font-size: 16px; } -tt.descname { padding-right:6px !important; } - -h1, h2, h3, h4, h5, h6, legend { - font-family:'Maven Pro' !important; - font-weight:normal; - text-align:center; -} -h3.navigation { text-align:left; } - -p.admonition-title { font-family: 'Raleway' !important; } - -body { font-family:'Raleway'; font-weight:normal; } -h1 { font-size: 36px; } -h2 { font-size: 24px; } -img { width:auto; } diff --git a/docs/templates/layout.html b/docs/templates/layout.html deleted file mode 100644 index d25829f..0000000 --- a/docs/templates/layout.html +++ /dev/null @@ -1,12 +0,0 @@ -{%- extends "alabaster/layout.html" %} -{%- block footer %} -
-
- {%- if sourcename %}source |{%- endif %} - {% if prev %}previous |{% endif %} - {% if next %}next |{% endif %} - index | - ©{{copyright}} -
-
-{%- endblock %} diff --git a/docs/templates/navigation.html b/docs/templates/navigation.html deleted file mode 100644 index ad5d7df..0000000 --- a/docs/templates/navigation.html +++ /dev/null @@ -1,4 +0,0 @@ -

Navigation

- diff --git a/docs/type-traits.rst b/docs/type-traits.rst index 4859793..f9e0282 100644 --- a/docs/type-traits.rst +++ b/docs/type-traits.rst @@ -63,7 +63,7 @@ header. attempting to discover the common type of two ``void&&``. Additionally, this type trait follows the C++14 rules of decaying the common type. -.. type:: is_nothrow_swappable +.. type:: template is_nothrow_swappable A type trait that is ``std::true_type`` if a given swap call on a type is actually marked as *noexcept*, and ``std::false_type`` otherwise. This trait @@ -73,20 +73,20 @@ header. :cxx:`is_nothrow_swappable` trait proposed in N4426_, and was added to MNMLSTC Core before the proposal was submitted. -.. type:: aligned_union +.. class:: template aligned_union This is an implementation of :cxx:`std::aligned_union`, and is provided for a certain compiler whose library implementations may not have added it until 2015-APR-22 and whose colloqiual pronunciation rhymes with "Pre Free Tea". That's "Free as in Tea", not "Free as in Speech" ;) -.. type:: bool_constant +.. type:: template bool_constant An alias of :cxx:`std::integral_constant`. This is a implementation of N4389_. -.. type:: tuple_element_t - tuple_size_t +.. type:: template tuple_element_t + template tuple_size_t These two type aliases are provided as they are missing from C++11. They are simply type aliases for :cxx:`std::tuple_element` and @@ -99,12 +99,12 @@ The detection idiom is a set of powerful meta templates that obviate the need for the 'old' approach to detecting if a member function, member, or function call would work for SFINAE purposes. It was originally started with Walter E. Brown's :any:`void_t`, but has since grown to include several -additional types such as :any:`is_detected`, `detected_or`, etc. +additional types such as :any:`is_detected`, :any:`detected_or`, etc. To give users a better idea, each entry has an example of how each part of the detection idiom would be used. -.. type:: void_t +.. type:: template void_t The infamous :any:`void_t` is a powerful SFINAE metaprogramming tool discovered by Walter E. Brown. It is used as the basis for @@ -112,23 +112,24 @@ the detection idiom would be used. :example: - .. code-block:: cpp + .. code-block:: cpp - // detect if class has a T::size() member function, but ignore the - // return type. - template - struct has_size_mem_fn : std::false_type { }; + // detect if class has a T::size() member function, but ignore the + // return type. + template + struct has_size_mem_fn : std::false_type { }; - template - struct has_size_mem_fn< - T, - void_t().size())> - > : std::true_type { }; + template + struct has_size_mem_fn< + T, + void_t().size())> + > : std::true_type { }; - static_assert(has_size_mem_fn::value, ""); - static_assert(not has_size_mem_fn::value, ""); + static_assert(has_size_mem_fn::value, ""); + static_assert(not has_size_mem_fn::value, ""); -.. type:: is_detected, Args...> +.. type:: template