From 8ade346d246965a65a21c52a3671326a056afbac Mon Sep 17 00:00:00 2001 From: James Mitchell Date: Thu, 19 Jun 2025 14:48:36 +0100 Subject: [PATCH 1/5] Update install.rst --- docs/source/install.rst | 77 +++++++++++++++++++---------------------- 1 file changed, 35 insertions(+), 42 deletions(-) diff --git a/docs/source/install.rst b/docs/source/install.rst index f3c6bfc56..4c353ab32 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -13,7 +13,8 @@ Installation Installing with pip ------------------- -It's possible to install ``libsemigroups_pybind11`` using ``pip`` via one of: +It's possible to install ``libsemigroups_pybind11`` using ``pip`` something +like the following (depending on your system and setup): :: @@ -21,35 +22,36 @@ It's possible to install ``libsemigroups_pybind11`` using ``pip`` via one of: pip3 install libsemigroups_pybind11 python -m pip install libsemigroups_pybind11 -Installing with conda ---------------------- -This installation method assumes that you have anaconda or miniconda installed. -See the `getting started`_ and `miniconda download page`_ on the conda_ website. - -.. _conda: https://conda.io/ - -.. _getting started: http://bit.ly/33B0Vfs - -.. _miniconda download page: https://conda.io/miniconda.html - -It might be a good idea to create and activate a conda environment to contain -the installation of the ``libsemigroups_pybind11``: - -:: - - conda create --name libsemigroups - conda activate libsemigroups - -Install ``libsemigroups_pybind11``: - -:: - - conda install -c conda-forge libsemigroups_pybind11 - -.. warning:: - - At present this does not work for Macs with M1 processors. +.. Installing with conda + --------------------- + + This installation method assumes that you have anaconda or miniconda installed. + See the `getting started`_ and `miniconda download page`_ on the conda_ website. + + .. _conda: https://conda.io/ + + .. _getting started: http://bit.ly/33B0Vfs + + .. _miniconda download page: https://conda.io/miniconda.html + + It might be a good idea to create and activate a conda environment to contain + the installation of the ``libsemigroups_pybind11``: + + :: + + conda create --name libsemigroups + conda activate libsemigroups + + Install ``libsemigroups_pybind11``: + + :: + + conda install -c conda-forge libsemigroups_pybind11 + + .. warning:: + + At present this does not work for Macs with M1 processors. From the sources ---------------- @@ -57,7 +59,7 @@ From the sources Before installing ``libsemigroups_pybind11`` from its sources you should first perform a system install of the C++ library ``libsemigroups``. For information about how to install ``libsemigroups`` see `the installation guide -`_. +`_. Assuming that you have ``libsemigroups`` installed you can install ``libsemigroups_pybind11`` as follows: @@ -84,21 +86,12 @@ To build ``libsemigroups_pybind11`` from a release archive: Building the documentation -------------------------- -The following are required to be able to build the documentation: - -1. ``python3`` -2. the python packages: ``jinja2 sphinx sphinx_rtd_theme sphinxcontrib-bibtex - sphinx_copybutton`` - -Assuming you already have ``python3`` install, on Mac OSX you can install all of -the above by doing: +Assuming you already have ``python3`` install, you can build the doc by using: :: - python3 -m pip3 install -r docs/requirements - -Then it ought to be possible to just run ``make doc`` in the ``libsemigroups`` -directory. + python3 -m pip3 install -r requirements.txt + make doc Issues ------ From 1fc3fdb544e761f9007d535126cb0df06cbd0dc0 Mon Sep 17 00:00:00 2001 From: James Mitchell Date: Thu, 19 Jun 2025 14:56:07 +0100 Subject: [PATCH 2/5] changelog: add changelog file for v1 and move v0 file --- .../source/{changelog.rst => changelog-v0.rst} | 4 ++-- docs/source/changelog-v1.rst | 14 ++++++++++++++ docs/source/index.rst | 18 ++++++------------ 3 files changed, 22 insertions(+), 14 deletions(-) rename docs/source/{changelog.rst => changelog-v0.rst} (99%) create mode 100644 docs/source/changelog-v1.rst diff --git a/docs/source/changelog.rst b/docs/source/changelog-v0.rst similarity index 99% rename from docs/source/changelog.rst rename to docs/source/changelog-v0.rst index 0dd5349b5..dcc3a75f3 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog-v0.rst @@ -5,8 +5,8 @@ The full license is in the file LICENSE, distributed with this software. -Changelog -========= +Changelog - version 0 +===================== v0.10.1 (released 29/03/2023) ----------------------------- diff --git a/docs/source/changelog-v1.rst b/docs/source/changelog-v1.rst new file mode 100644 index 000000000..bb5ff00ff --- /dev/null +++ b/docs/source/changelog-v1.rst @@ -0,0 +1,14 @@ +.. + Copyright (c) 2025, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Changelog - version 1 +===================== + +v1.0.0 (released ??/??/202?) +----------------------------- + +TODO diff --git a/docs/source/index.rst b/docs/source/index.rst index 7d64f4492..99e482ad2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -49,10 +49,11 @@ How to use it See the installation instructions: * :doc:`install` - * :doc:`changelog` + * :doc:`changelog-v1` The structure of the module ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The Python module ``libsemigroups_pybind11`` was designed to mirror the C++ library ``libsemigroups`` as closely as possible, whilst navigating the fundamental difference between Python and C++. This is done with the help of the @@ -105,16 +106,8 @@ defined upon. These may appear in error messages. For example: The :doc:`authors ` of ``libsemigroups_pybind11`` have gone to a lot of effort to try and make error messages clear, specific and intelligible; however, -if there you encounter any errors with unclear messages, please raise this on -the `issue tracker`_. - -Further Info ------------- - -For additional information about ``libsemigroups_pybind11``, see the following: - - * :doc:`authors` - * :doc:`biblio` +if you encounter any errors with unclear messages, please let us know on the +`issue tracker`_. .. toctree:: :caption: Package Info @@ -122,7 +115,8 @@ For additional information about ``libsemigroups_pybind11``, see the following: :hidden: install - changelog + changelog-v1 + changelog-v0 authors biblio From 73995078b4da7c0553f6a07f19917cb9db6a9a74 Mon Sep 17 00:00:00 2001 From: James Mitchell Date: Thu, 19 Jun 2025 15:51:51 +0100 Subject: [PATCH 3/5] doc: update installation + some more rejigging --- docs/source/data-structures/misc/index.rst | 21 ---- .../misc/libsemigroups-error.rst | 51 --------- .../data-structures/presentations/index.rst | 10 +- .../{misc => presentations}/obvinf.rst | 0 docs/source/index.rst | 88 +++----------- docs/source/libsemigroups-error.rst | 107 ++++++++++++++++++ 6 files changed, 126 insertions(+), 151 deletions(-) delete mode 100644 docs/source/data-structures/misc/index.rst delete mode 100644 docs/source/data-structures/misc/libsemigroups-error.rst rename docs/source/data-structures/{misc => presentations}/obvinf.rst (100%) create mode 100644 docs/source/libsemigroups-error.rst diff --git a/docs/source/data-structures/misc/index.rst b/docs/source/data-structures/misc/index.rst deleted file mode 100644 index a16a830f0..000000000 --- a/docs/source/data-structures/misc/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. - Copyright (c) 2021-2024 J. D. Mitchell - - Distributed under the terms of the GPL license version 3. - - The full license is in the file LICENSE, distributed with this software. - -Miscellaneous -============= - -In this section we describe some miscellaneous functionality in -``libsemigroups_pybind11``. - -.. toctree:: - :maxdepth: 1 - - obvinf - libsemigroups-error - -.. - ukkonen/index diff --git a/docs/source/data-structures/misc/libsemigroups-error.rst b/docs/source/data-structures/misc/libsemigroups-error.rst deleted file mode 100644 index 0dd2d4db2..000000000 --- a/docs/source/data-structures/misc/libsemigroups-error.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. - Copyright (c) 2024 Joseph Edwards - - Distributed under the terms of the GPL license version 3. - - The full license is in the file LICENSE, distributed with this software. - -.. currentmodule:: libsemigroups_pybind11 - -Exceptions -========== - -This page describes the custom error type used in ``libsemigroups_pybind11``, -namely :any:`LibsemigroupsError`, and related functions. Other built-in -exceptions, such as :any:`ValueError` and :any:`TypeError`, may also be raised -in this project. See the -`Python documentation `_ -for further details. - -Full API --------- - -.. autoexception:: LibsemigroupsError - :show-inheritance: - - This is the main type of exception raised by the custom data-structures and - algorithms of ``libsemigroups_pybind11``. It is raised when the underlying - C++ code from libsemigroups_ raises a ``LibsemigroupsException``. - - .. doctest:: python - - >>> from libsemigroups_pybind11 import FroidurePin, Perm - >>> gens = [Perm([3, 0, 1, 2]), Perm([1, 2, 0, 3]), Perm([2, 1, 0, 3])] - >>> S = FroidurePin(gens) - >>> S - - - >>> S.generator(3) # Bad: there are only three generators - Traceback (most recent call last): - ... - LibsemigroupsError: generator index out of bounds, expected value in [0, 3), got 3 - - .. note:: - - If you believe your code is incorrectly throwing a - :any:`LibsemigroupsError`, or isn't throwing a :any:`LibsemigroupsError` - but you think it should, please let us known by opening an issue on the - `issue tracker`_. - -.. autofunction:: error_message_with_prefix - diff --git a/docs/source/data-structures/presentations/index.rst b/docs/source/data-structures/presentations/index.rst index 8e830b59b..34117135c 100644 --- a/docs/source/data-structures/presentations/index.rst +++ b/docs/source/data-structures/presentations/index.rst @@ -15,7 +15,8 @@ the finite presentations on which these algorithms can be run is described below. In ``libsemigroups_pybind11``, a presentation is modelled as a collection of -*rules*, each of which is a pair of *words*. Each word is made up of *letters*. +*rules*, each of which is a pair of *words* (although these rules are stored as +a non-nested list with the left- and right-hand sides in the even and odd indexed positions respectively). Each word is made up of *letters*. Presently, for any given presentation, all letters must either be of the type :any:`str` or :any:`int`. In a presentation where letters are of the type :any:`str`, words have the type :any:`str`. In a presentation where letters are @@ -28,12 +29,6 @@ In what follows, we will use the pseudo-types ``Letter`` and ``Word`` instead of ``str | int`` and ``str | list[int]`` to further indicate that two types of letters and words cannot be interchanged once a presentation is constructed. -All of the classes for finitely presented semigroups and monoids in -``libsemigroups_pybind11`` can be used "interactively", in the sense that they -can be run for a particular amount of time, or until some condition is met; for -further details see, for example, :any:`Runner.run_for` and -:any:`Runner.run_until`. - The classes and modules in ``libsemigroups_pybind11`` for finitely presented semigroups and monoids are: @@ -47,3 +42,4 @@ semigroups and monoids are: examples to-present to-inverse-present + obvinf diff --git a/docs/source/data-structures/misc/obvinf.rst b/docs/source/data-structures/presentations/obvinf.rst similarity index 100% rename from docs/source/data-structures/misc/obvinf.rst rename to docs/source/data-structures/presentations/obvinf.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 99e482ad2..e5615f0df 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,13 +5,12 @@ .. title:: libsemigroups_pybind11 -Python bindings for the C++ library libsemigroups -------------------------------------------------- +| -What is ``libsemigroups``? +What is libsemigroups_? ~~~~~~~~~~~~~~~~~~~~~~~~~~ -``libsemigroups`` is a C++14 library containing implementations of several +libsemigroups_ is a C++14 library containing implementations of several algorithms for computing finite and finitely presented semigroups. Namely: - the `Froidure-Pin algorithm`_ for computing finite semigroups @@ -22,7 +21,7 @@ algorithms for computing finite and finitely presented semigroups. Namely: algorithm for computing finite semigroups which act on sets. ``libsemigroups_pybind11`` is a python package exposing much (but not all) of -the functionality of ``libsemigroups``. +the functionality of libsemigroups_. The development version of ``libsemigroups_pybind11`` is available on github_, and some related projects are here_. @@ -43,82 +42,28 @@ and some related projects are here_. .. _todd-coxeter algorithm: https://en.wikipedia.org/wiki/Todd%E2%80%93Coxeter_algorithm +.. _libsemigroups: https://libsemigroups.github.io/libsemigroups/index.html + How to use it ~~~~~~~~~~~~~ -See the installation instructions: - - * :doc:`install` - * :doc:`changelog-v1` - -The structure of the module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Python module ``libsemigroups_pybind11`` was designed to mirror the C++ -library ``libsemigroups`` as closely as possible, whilst navigating the -fundamental difference between Python and C++. This is done with the help of the -tool `pybind11 `_. - -For various implementational reasons (mostly related to Python's lack of an -analogue for C++'s templating system), the Python code exposed by ``pybind11`` -is less streamlined and concise than the C++ library. To try and address this, -the authors of ``libsemigroups_pybind11`` have further wrapped the Python code -produced by ``pybind11`` to make the Python and C++ user experience as similar -as possible. - -The Python bindings of the ``libsemigroups`` code produced by ``pybind11`` -reside in an intermediate module called ``_libsemigroups_pybind11`` (note the -leading underscore), and the public-facing nicely wrapped code resides in this -module — ``libsemigroups_pybind11``. - -Should this impact the way you, the user, use ``libsemigroups_pybind11``? For -the most part, no. It should be possible to use ``libsemigroups_pybind11`` in -the ways documented on this site without the knowledge that -``_libsemigroups_pybind11`` even exists. The notable exceptions to this relate -to type names and error messages. A lot of the code in -``libsemigroups_pybind11`` has been imported from ``_libsemigroups_pybind11``, -and this is visible in qualified type names. For example: - -.. doctest:: python - - >>> from libsemigroups_pybind11 import WordGraph - >>> WordGraph - - -Additionally, some functions or classes in the ``_libsemigroups_pybind11`` -module have additional prefixes and suffixes relative to their -``libsemigroups_pybind11`` counterpart. These usually relate to the module that -the function or class is contained within or a type the function or class is -defined upon. These may appear in error messages. For example: - -.. doctest:: python - - >>> from libsemigroups_pybind11 import aho_corasick, AhoCorasick - >>> ac = AhoCorasick() - >>> aho_corasick.add_word(ac, False) - Traceback (most recent call last): - ... - TypeError: aho_corasick_add_word(): incompatible function arguments. The following argument types are supported: - 1. (ac: _libsemigroups_pybind11.AhoCorasick, w: list[int]) -> int - 2. (ac: _libsemigroups_pybind11.AhoCorasick, w: str) -> int - - Invoked with: , False - -The :doc:`authors ` of ``libsemigroups_pybind11`` have gone to a lot of -effort to try and make error messages clear, specific and intelligible; however, -if you encounter any errors with unclear messages, please let us know on the -`issue tracker`_. +See the installation instructions :doc:`install`. + +If you encounter any issues with the package or have any suggestions, then +please let us know on the `issue tracker`_. + .. toctree:: :caption: Package Info :maxdepth: 1 :hidden: - install - changelog-v1 - changelog-v0 authors biblio + changelog-v1 + changelog-v0 + libsemigroups-error + install .. toctree:: :caption: Data Structures @@ -128,12 +73,11 @@ if you encounter any errors with unclear messages, please let us know on the data-structures/constants/index data-structures/elements/index data-structures/enums/index - data-structures/misc/index data-structures/order/index data-structures/presentations/index data-structures/suffix-trees/index - data-structures/tries/index data-structures/to-function + data-structures/tries/index data-structures/visualisation/index data-structures/word-graph/index data-structures/words/index diff --git a/docs/source/libsemigroups-error.rst b/docs/source/libsemigroups-error.rst new file mode 100644 index 000000000..2aa3ca7de --- /dev/null +++ b/docs/source/libsemigroups-error.rst @@ -0,0 +1,107 @@ +.. + Copyright (c) 2024 Joseph Edwards + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. currentmodule:: libsemigroups_pybind11 + +Exceptions +========== + +This page describes the custom error type used in ``libsemigroups_pybind11``, +namely :any:`LibsemigroupsError`, and related functions. Other built-in +exceptions, such as :any:`ValueError` and :any:`TypeError`, may also be raised +in this project. See the +`Python documentation `_ +for further details. + +The Python module ``libsemigroups_pybind11`` was designed to mirror the C++ +library libsemigroups_ as closely as possible, whilst navigating the +fundamental difference between Python and C++. This is done with the help of +`pybind11 `_. + +For various implementational reasons (mostly related to Python's lack of an +analogue for C++'s templating system), the Python code exposed by ``pybind11`` +is less streamlined and concise than the C++ library. To try and address this, +the authors of ``libsemigroups_pybind11`` have further wrapped the Python code +produced by ``pybind11`` to make the Python and C++ user experience as similar +as possible. + +The Python bindings of the libsemigroups_ code produced by ``pybind11`` +reside in an intermediate module called ``_libsemigroups_pybind11`` (note the +leading underscore), and the public-facing nicely wrapped code resides in this +module — ``libsemigroups_pybind11``. + +Should this impact the way you, the user, use ``libsemigroups_pybind11``? For +the most part, no. It should be possible to use ``libsemigroups_pybind11`` in +the ways documented on this site without the knowledge that +``_libsemigroups_pybind11`` even exists. The notable exceptions to this relate +to type names and error messages. A lot of the code in +``libsemigroups_pybind11`` has been imported from ``_libsemigroups_pybind11``, +and this is visible in qualified type names. For example: + +.. doctest:: python + + >>> from libsemigroups_pybind11 import WordGraph + >>> WordGraph + + +Additionally, some functions or classes in the ``_libsemigroups_pybind11`` +module have additional prefixes and suffixes relative to their +``libsemigroups_pybind11`` counterpart. These usually relate to the module that +the function or class is contained within or a type the function or class is +defined upon. These may appear in error messages. For example: + +.. doctest:: python + + >>> from libsemigroups_pybind11 import aho_corasick, AhoCorasick + >>> ac = AhoCorasick() + >>> aho_corasick.add_word(ac, False) + Traceback (most recent call last): + ... + TypeError: aho_corasick_add_word(): incompatible function arguments. The following argument types are supported: + 1. (ac: _libsemigroups_pybind11.AhoCorasick, w: list[int]) -> int + 2. (ac: _libsemigroups_pybind11.AhoCorasick, w: str) -> int + + Invoked with: , False + +The authors of ``libsemigroups_pybind11`` have gone to a lot of effort to try +and make error messages clear, specific and intelligible; however, if you +encounter any errors with unclear messages, please let us know on the +`issue tracker`_. + +Full API +-------- + +.. autoexception:: LibsemigroupsError + :show-inheritance: + + This is the main type of exception raised by the custom data-structures and + algorithms of ``libsemigroups_pybind11``. It is raised when the underlying + C++ code from libsemigroups_ raises a ``LibsemigroupsException``. + + .. doctest:: python + + >>> from libsemigroups_pybind11 import FroidurePin, Perm + >>> gens = [Perm([3, 0, 1, 2]), Perm([1, 2, 0, 3]), Perm([2, 1, 0, 3])] + >>> S = FroidurePin(gens) + >>> S + + + >>> S.generator(3) # Bad: there are only three generators + Traceback (most recent call last): + ... + LibsemigroupsError: generator index out of bounds, expected value in [0, 3), got 3 + + .. note:: + + If you believe your code is incorrectly throwing a + :any:`LibsemigroupsError`, or isn't throwing a :any:`LibsemigroupsError` + but you think it should, please let us known by opening an issue on the + `issue tracker`_. + +.. autofunction:: error_message_with_prefix + +.. _libsemigroups: https://libsemigroups.github.io/libsemigroups/index.html From 2c6227d867e0a44e5817023d741dd29f489e8481 Mon Sep 17 00:00:00 2001 From: James Mitchell Date: Thu, 19 Jun 2025 15:52:02 +0100 Subject: [PATCH 4/5] Add Reinis as co-author --- docs/source/authors.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/authors.rst b/docs/source/authors.rst index 8df156253..3112338d5 100644 --- a/docs/source/authors.rst +++ b/docs/source/authors.rst @@ -10,6 +10,7 @@ Authors ======= +- `Reinis Cirpons`_ (rc234@st-andrews.ac.uk)_ - `Joseph Edwards`_ (jde1@st-andrews.ac.uk) - `James Mitchell`_ (jdm3@st-andrews.ac.uk) - `Maria Tsalakou`_ (mt200@st-andrews.ac.uk) @@ -21,6 +22,8 @@ Authors .. _maria tsalakou: https://mariatsalakou.github.io/ +.. _reinis cirpons: https://reinisc.id.lv + Contributors ------------ From e29d3968dde8af630f715c4bf436a78409abdee1 Mon Sep 17 00:00:00 2001 From: Joseph Edwards Date: Thu, 26 Jun 2025 17:21:23 +0100 Subject: [PATCH 5/5] Doc: Changes from review --- docs/source/{ => _static}/links.rst | 0 docs/source/conf.py | 6 ++- docs/source/index.rst | 2 - docs/source/install.rst | 58 ++++++++++++++++++----------- docs/source/libsemigroups-error.rst | 2 - 5 files changed, 40 insertions(+), 28 deletions(-) rename docs/source/{ => _static}/links.rst (100%) diff --git a/docs/source/links.rst b/docs/source/_static/links.rst similarity index 100% rename from docs/source/links.rst rename to docs/source/_static/links.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 6ca16dc8d..f929db90f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -27,7 +27,7 @@ rst_epilog = "" # Read link all targets from file -with open("links.rst", encoding="utf-8") as f: +with open("_static/links.rst", encoding="utf-8") as f: rst_epilog += f.read() autosummary_generate = True @@ -46,7 +46,9 @@ # Use the version number of the installed project version = release = importlib.metadata.version(project) language = "python" -exclude_patterns = ["_build", "_old", "links.rst"] +exclude_patterns = ["_build", "_old", "_static"] +# Don't copy the prompt characters +copybutton_exclude = ".linenos, .gp" pygments_style = "sphinx" highlight_language = "python" todo_include_todos = False diff --git a/docs/source/index.rst b/docs/source/index.rst index e5615f0df..41aad30f5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -42,8 +42,6 @@ and some related projects are here_. .. _todd-coxeter algorithm: https://en.wikipedia.org/wiki/Todd%E2%80%93Coxeter_algorithm -.. _libsemigroups: https://libsemigroups.github.io/libsemigroups/index.html - How to use it ~~~~~~~~~~~~~ diff --git a/docs/source/install.rst b/docs/source/install.rst index 4c353ab32..7155d1d5d 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -5,22 +5,29 @@ The full license is in the file LICENSE, distributed with this software. -.. |libsemigroups-pybind11-version| replace:: 1.0.0 - Installation ============ Installing with pip ------------------- -It's possible to install ``libsemigroups_pybind11`` using ``pip`` something -like the following (depending on your system and setup): +It's possible to install ``libsemigroups_pybind11`` using ``pip`` by doing one +of the following (depending on your system and setup): + +.. highlight:: console :: - pip install libsemigroups_pybind11 - pip3 install libsemigroups_pybind11 - python -m pip install libsemigroups_pybind11 + $ pip install libsemigroups_pybind11 + + +:: + + $ pip3 install libsemigroups_pybind11 + +:: + + $ python -m pip install libsemigroups_pybind11 .. Installing with conda @@ -56,46 +63,53 @@ like the following (depending on your system and setup): From the sources ---------------- -Before installing ``libsemigroups_pybind11`` from its sources you should first +Before installing ``libsemigroups_pybind11`` from its sources, you should first perform a system install of the C++ library ``libsemigroups``. For information -about how to install ``libsemigroups`` see `the installation guide +about how to do this, see the `libsemigroups installation guide `_. -Assuming that you have ``libsemigroups`` installed you can install +Assuming that you have ``libsemigroups`` installed, you can install ``libsemigroups_pybind11`` as follows: :: - git clone https://github.com/libsemigroups/libsemigroups_pybind11 - cd libsemigroups_pybind11 - pip install . + $ git clone https://github.com/libsemigroups/libsemigroups_pybind11 + $ cd libsemigroups_pybind11 + $ pip install . From a release archive ~~~~~~~~~~~~~~~~~~~~~~ To build ``libsemigroups_pybind11`` from a release archive: +.. Unfortunately, text replacement doesn't work inside of code blocks, so it is + necessary to update the version number below manually. + :: - curl -L -O https://github.com/libsemigroups/libsemigroups_pybind11/releases/latest/download/libsemigroups_pybind11-|libsemigroups-pybind11-version|.tar.gz - tar -xf libsemigroups_pybind11-|libsemigroups-pybind11-version|.tar.gz - rm -f libsemigroups_pybind11-|libsemigroups-pybind11-version|.tar.gz - cd libsemigroups_pybind11-|libsemigroups-pybind11-version| - pip install . + $ curl -L -O https://github.com/libsemigroups/libsemigroups_pybind11/releases/latest/download/libsemigroups_pybind11-1.0.0.tar.gz + $ tar -xf libsemigroups_pybind11-1.0.0.tar.gz + $ rm -f libsemigroups_pybind11-1.0.0.tar.gz + $ cd libsemigroups_pybind11-1.0.0 + $ pip install . Building the documentation -------------------------- -Assuming you already have ``python3`` install, you can build the doc by using: +Assuming you have ``python3`` and ``make`` installed, you can build the doc by +using: :: - python3 -m pip3 install -r requirements.txt - make doc + $ python3 -m pip3 install -r requirements.txt + $ make doc + +If you don't have ``make``, you can run the executable ``./etc/make-doc.sh`` +instead of running ``make doc`` (which is precisely what ``make doc`` does). Issues ------ If you find any problems with ``libsemigroups_pybind11``, or have any -suggestions for features that you’d like to see, please use the +suggestions for features that you'd like to see, please use the `issue tracker`_. diff --git a/docs/source/libsemigroups-error.rst b/docs/source/libsemigroups-error.rst index 2aa3ca7de..47ceef4e7 100644 --- a/docs/source/libsemigroups-error.rst +++ b/docs/source/libsemigroups-error.rst @@ -103,5 +103,3 @@ Full API `issue tracker`_. .. autofunction:: error_message_with_prefix - -.. _libsemigroups: https://libsemigroups.github.io/libsemigroups/index.html