Documentation overhaul (again!)

Doxyfile

@@ -2299,7 +2299,8 @@ PREDEFINED             =      LIBRAPID_USE_MULTIPREC=\
                               LIBRAPID_HAS_OMP=\
                               LIBRAPID_NODISCARD=\
                               LIBRAPID_ALWAYS_INLINE=\
-                              LIBRAPID_INLINE=
+                              LIBRAPID_INLINE=\
+                              LIBRAPID_RELEASE_NOEXCEPT=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

README.md

@@ -105,24 +105,17 @@ hopefully it's clear to see how powerful this could be when working with more co
 
 # Documentation
 
-<a href="https://docs.hdoc.io/pencilcaseman/LibRapid/index.html" target="_blank"><b>Latest
-Documentation</b></a>
+<a href="https://librapid.readthedocs.io/en/latest/" target="_blank"><b>Latest
+Documentation</b></a> \
+<a href="https://librapid.readthedocs.io/en/develop/" target="_blank"><b>Develop Branch Docs</b></a>
 
-LibRapid uses [HDoc](https://hdoc.io/) to automatically parse source files and extract the commented documentation
-for each symbol. This is the most up-to-date documentation available, and is the easiest way to get started with
-LibRapid.
+LibRapid uses [Doxygen](https://doxygen.nl/) to parse the source code and extract documentation information. We then use
+a combination
+of [Breathe](https://breathe.readthedocs.io/en/latest/), [Exhale](https://exhale.readthedocs.io/en/latest/)
+and [Sphinx](https://www.sphinx-doc.org/en/master/) to generate a website from this data. The final website is hosted on
+[Read the Docs](https://readthedocs.org/).
 
-LibRapid also supports documentation generation via [Doxygen](https://doxygen.nl/), the hosted version of which
-can be found [here](https://librapid.github.io/librapid/). There are also PDFs
-available from the [Build Documentation](https://github.com/LibRapid/librapid/actions/workflows/build-docs.yaml)
-GitHub Action.
-
-> **Warning**
-> While the Doxygen documentation will contain up-to-date code comments, the examples, tutorials and other 
-> information may not be up-to-date or exist at all.
-
-LibRapid uses [Doxygen](https://doxygen.nl/) to automatically generate the documentation, and
-[Doxygen Awesome CSS](https://github.com/jothepro/doxygen-awesome-css) to improve Doxygen's outdated styling.
+The documentation is rebuilt every time a change is made to the source code, meaning it is always up-to-date.
 
 # Current Development Stage
 
@@ -192,9 +185,3 @@ Thanks to JetBrains for providing LibRapid with free licenses for their amazing
     <img src="https://devclass.com/wp-content/uploads/2018/12/jetbrains-variant-4.png" alt="JetBrains" width="200"/>
   </a>
 </p>
-
-# License Status
-
-<div align="center">
-<a href="https://app.fossa.com/projects/git%2Bgithub.com%2FLibRapid%2Flibrapid?ref=badge_large" alt="FOSSA Status"><img src="https://app.fossa.com/api/projects/git%2Bgithub.com%2FLibRapid%2Flibrapid.svg?type=large"/></a>
-</div>

docs/requirements.txt

@@ -5,4 +5,5 @@ furo==2022.9.29
 pydata-sphinx-theme==0.11.0
 numpydoc==1.5.0
 sphinx-panels==0.6.0
-regex
+regex
+sphinx-favicon

docs/source/caution.rst

@@ -0,0 +1,50 @@
+Caution
+#######
+
+.. warning::
+
+    LibRapid developers had to make certain decisions regarding the underlying data layout used by the library. We made
+    these decisions with the best interests of the library in mind, and while they may improve performance or usability,
+    they may also incur adverse side effects.
+
+    While the developers of LibRapid may not be aware of all the side effects of their design choices, we have done our
+    best to identify and justify those we know of.
+
+Array Referencing Issues
+------------------------
+
+LibRapid uses lazy evaluation to reduce the number of intermediate variables and copies required for any given
+operation, significantly improving performance. A side effect of this is that combined operations store references to
+Array objects.
+
+As a result, if any of the referenced Array instances go out of scope before the lazy object is evaluated, an invalid
+memory location will be accessed, incurring a segmentation fault.
+
+The easiest fix for this is to make sure you evaluate temporary results in time, though this is easier said than done.
+LibRapid aims to identify when a lazy object is using an invalid value and notify the user, but this will not work in
+all cases.
+
+The code below will cause a segmentation fault since ``testArray`` will go out of scope upon returning from the function
+while the returned object contains two references to the array.
+
+.. code-block:: cpp
+    :linenos:
+
+    /* References invalid memory
+    vvvv */
+    auto doesThisBreak() {
+        lrc::Array<float> testArray(lrc::Shape({3, 3}));
+        testArray << 1, 2, 3, 4, 5, 6, 7, 8, 9;
+        return testArray + testArray;
+    }
+
+.. code-block:: cpp
+    :linenos:
+
+    /*   Changed
+    -------vvv------- */
+    lrc::Array<float> doesThisBreak() {
+        lrc::Array<float> testArray(lrc::Shape({3, 3}));
+        testArray << 1, 2, 3, 4, 5, 6, 7, 8, 9;
+        return testArray + testArray;
+    }

docs/source/cmakeIntegration.rst

@@ -0,0 +1,33 @@
+CMake Integration
+#################
+
+Installation
+------------
+
+Link librapid like any other CMake library:
+
+Clone the repository:
+``git clone --recursive https://github.com/LibRapid/libRapid.git``
+
+Add the following to your ``CMakeLists.txt``
+
+.. code-block:: cmake
+
+    add_subdirectory(librapid)
+    target_link_libraries(yourTarget PUBLIC librapid)
+
+CMake Options
+-------------
+
+When using LibRapid in your CMake project, the following options are configurable:
+
+- ``LIBRAPID_BUILD_EXAMPLES => OFF`` (Build examples?)
+- ``LIBRAPID_BUILD_TESTS => OFF`` (Build tests?)
+- ``LIBRAPID_STRICT => OFF`` (Force warnings into errors?)
+- ``LIBRAPID_QUIET => OFF`` (Disable warnings)
+- ``LIBRAPID_GET_BLAS => OFF`` (Clone a prebuilt version of OpenBLAS?)
+- ``LIBRAPID_USE_CUDA => ON`` (Automatically search for CUDA?)
+- ``LIBRAPID_USE_OMP => ON`` (Automatically search for OpenMP?)
+- ``LIBRAPID_USE_MULTIPREC => OFF`` (Include multiprecision library -- more on this elsewhere in documentation)
+- ``LIBRAPID_OPTIMISE_SMALL_ARRAYS => OFF`` (Optimise small arrays?)
+- ``LIBRAPID_FAST_MATH => OFF`` (Use potentially less accurate operations to increase performance)