Merge pull request #346 from bluescarni/pr/docs

Initial WIP on docs

config.hpp.in

@@ -31,6 +31,12 @@
 
 #endif
 
+#if !defined(MPPP_WITH_FMT)
+
+#error mp++ must be configured with support for the fmt library.
+
+#endif
+
 #if defined(MPPP_WITH_QUADMATH)
 
 #define HEYOKA_HAVE_REAL128

doc/api_reference.rst

@@ -0,0 +1,15 @@
+.. _api_reference:
+
+API Reference
+=============
+
+The following subsections contain the detailed documentation of all of heyoka's public classes and functions.
+
+.. toctree::
+   :maxdepth: 2
+
+   definitions.rst
+   namespaces.rst
+   kwargs.rst
+   exceptions.rst
+   expression_system.rst

doc/changelog.rst

@@ -7,6 +7,7 @@ Changelog
 New
 ~~~
 
+- Support LLVM 17 (`#346 <https://github.com/bluescarni/heyoka/pull/346>`__).
 - Add model for the circular restricted three-body problem
   (`#345 <https://github.com/bluescarni/heyoka/pull/345>`__).
 - heyoka can now automatically vectorise scalar calls to

doc/definitions.rst

@@ -0,0 +1,38 @@
+Macros and definitions
+======================
+
+*#include <heyoka/config.hpp>*
+
+.. c:macro:: HEYOKA_VERSION_STRING
+
+   This definition expands to a string literal containing the full version of the heyoka library
+   (e.g., for version 1.2.3 this macro expands to ``"1.2.3"``).
+
+.. c:macro:: HEYOKA_VERSION_MAJOR
+
+   This definition expands to an integral literal corresponding to heyoka's major version number (e.g.,
+   for version 1.2.3, this macro expands to ``1``).
+
+.. c:macro:: HEYOKA_VERSION_MINOR
+
+   This definition expands to an integral literal corresponding to heyoka's minor version number (e.g.,
+   for version 1.2.3, this macro expands to ``2``).
+
+.. c:macro:: HEYOKA_VERSION_PATCH
+
+   This definition expands to an integral literal corresponding to heyoka's patch version number (e.g.,
+   for version 1.2.3, this macro expands to ``3``).
+
+.. c:macro:: HEYOKA_WITH_MPPP
+
+   This name is defined if heyoka was built with support for the mp++ library (see the :ref:`installation instructions <installation>`).
+
+.. c:macro:: HEYOKA_WITH_REAL128
+.. c:macro:: HEYOKA_WITH_REAL
+
+    These names are defined if heyoka was built with support for, respectively, the :cpp:class:`~mppp::real128` and :cpp:class:`~mppp::real` classes from
+    the mp++ library (see the :ref:`installation instructions <installation>`).
+
+.. c:macro:: HEYOKA_WITH_SLEEF
+
+   This name is defined if heyoka was built with support for the SLEEF library (see the :ref:`installation instructions <installation>`).

doc/exceptions.rst

@@ -0,0 +1,15 @@
+.. _exceptions:
+
+Exceptions
+==========
+
+*#include <heyoka/exceptions.hpp>*
+
+.. cpp:namespace-push:: heyoka
+
+.. cpp:class:: not_implemented_error final : public std::runtime_error
+
+   Exception to signal that a feature/functionality is not implemented.
+
+   This exception inherits all members (including constructors) from
+   `std::runtime_error <https://en.cppreference.com/w/cpp/error/runtime_error>`_.

doc/expression.rst

@@ -0,0 +1,11 @@
+Expressions
+===========
+
+*#include <heyoka/expression.hpp>*
+
+The :cpp:class:`~heyoka::expression` class
+------------------------------------------
+
+.. cpp:namespace-push:: heyoka
+
+.. cpp:class:: expression

doc/expression_system.rst

@@ -0,0 +1,19 @@
+.. _expression_system:
+
+Expression system
+=================
+
+List node types.
+
+Mention that expression system API is immutable.
+
+Mention reference semantics for non-trivial expressions.
+
+.. toctree::
+   :maxdepth: 1
+
+   variable.rst
+   number.rst
+   param.rst
+   func.rst
+   expression.rst

doc/func.rst

@@ -0,0 +1,121 @@
+Functions
+=========
+
+*#include <heyoka/func.hpp>*
+
+The :cpp:class:`~heyoka::func_base` class
+-----------------------------------------
+
+.. cpp:namespace-push:: heyoka
+
+.. cpp:class:: func_base
+
+   This is the base class of all functions implemented in the :ref:`expression system<expression_system>`.
+
+   It provides a common interface for constructing functions and accessing their arguments.
+
+   .. cpp:function:: explicit func_base(std::string name, std::vector<expression> args)
+
+      Constructor from name and arguments.
+
+      :param name: the function name.
+      :param args: the function arguments.
+
+      :exception: any exceptions raised by copying the name or the arguments.
+      :exception std\:\:invalid_argument: if *name* is empty.
+
+   .. cpp:function:: func_base(const func_base &)
+   .. cpp:function:: func_base(func_base &&) noexcept
+   .. cpp:function:: func_base &operator=(const func_base &)
+   .. cpp:function:: func_base &operator=(func_base &&) noexcept
+   .. cpp:function:: ~func_base()
+
+      :cpp:class:`func_base` is copy/move constructible, copy/move assignable and destructible.
+
+      :exception: any exception thrown by the copy constructor/copy assignment operator the function's name or arguments.
+
+   .. cpp:function:: [[nodiscard]] const std::string &get_name() const noexcept
+
+      Name getter.
+
+      :return: a reference to the function's name.
+
+   .. cpp:function:: [[nodiscard]] const std::vector<expression> &args() const noexcept
+
+      Arguments getter.
+
+      :return: a reference to the function's arguments.
+
+The :cpp:class:`~heyoka::func` class
+------------------------------------
+
+.. cpp:class:: func
+
+   This class is used to represent functions in the :ref:`expression system<expression_system>`.
+
+   :cpp:class:`func` is a polymorphic wrapper that can be constructed from any
+   object satisfying certain conceptual requirements. We refer to such objects as
+   *user-defined functions*, or UDFs (see the :cpp:concept:`is_udf` concept).
+
+   The polymorphic wrapper is implemented internally via ``std::shared_ptr``, and thus
+   :cpp:class:`func` employs reference semantics: copy construction and copy assignment
+   do not throw, and they are constant-time operations.
+
+   .. note::
+
+      At this time, the :cpp:class:`func` API is still in flux and as such
+      it is largely undocumented. Please refer to the source
+      code if you need to understand the full API.
+
+   .. cpp:function:: func()
+
+      Default constructor.
+
+      The default constructor will initialise this :cpp:class:`func` object
+      with an implementation-defined UDF.
+
+      :exception: any exception thrown by memory allocation failures.
+
+   .. cpp:function:: template <typename T> requires (!std::same_as<func, std::remove_cvref_t<T>>) && is_udf<std::remove_cvref_t<T>> explicit func(T &&x)
+
+      Generic constructor.
+
+      This constructor will initialise ``this`` with the user-defined function *x*.
+
+      :exception: any exception thrown by memory allocation failures or by the copy/move constructor of the user-defined function *x*.
+
+   .. cpp:function:: func(const func &) noexcept
+   .. cpp:function:: func(func &&) noexcept
+   .. cpp:function:: func &operator=(const func &) noexcept
+   .. cpp:function:: func &operator=(func &&) noexcept
+   .. cpp:function:: ~func()
+
+      :cpp:class:`func` is copy/move constructible, copy/move assignable and destructible.
+
+      The only valid operations on a moved-from :cpp:class:`func` are destruction and copy/move assignment.
+
+   .. cpp:function:: [[nodiscard]] const std::string &get_name() const noexcept
+
+      Name getter.
+
+      This getter will invoke :cpp:func:`func_base::get_name()` on the internal UDF.
+
+      :return: a reference to the function's name.
+
+   .. cpp:function:: [[nodiscard]] const std::vector<expression> &args() const noexcept
+
+      Arguments getter.
+
+      This getter will invoke :cpp:func:`func_base::args()` on the internal UDF.
+
+      :return: a reference to the function's arguments.
+
+Concepts
+--------
+
+.. cpp:concept:: template <typename T> is_udf = std::default_initializable<T> && std::copy_constructible<T> && std::move_constructible<T> && std::destructible<T> && std::derived_from<T, func_base>
+
+   User-defined function concept.
+
+   This concept enumerates the minimum requirements of user-defined functions (UDFs), that is, objects that
+   can be used to construct a :cpp:class:`func`.

doc/index.rst

@@ -115,6 +115,7 @@ Dario Izzo (European Space Agency).
    install.rst
    basic_tutorials.rst
    advanced_tutorials.rst
+   api_reference.rst
    benchmarks.rst
    ad_notes.rst
    changelog.rst

doc/kwargs.rst

@@ -0,0 +1,6 @@
+.. _kwargs:
+
+Keyword arguments
+=================
+
+TBD

doc/namespaces.rst

@@ -0,0 +1,9 @@
+Namespaces
+==========
+
+All the functionality of the library is included within the ``heyoka`` namespace.
+
+The ``inline`` namespace ``heyoka::literals`` contains several user-defined literals (e.g., for the creation of an expression from
+a floating-point literal).
+
+The namespace ``heyoka::kw`` contains the :ref:`keyword arguments <kwargs>` used throughout the heyoka API.