Merge pull request #275 from saraedum/breathe

Build documentation with breathe

.github/workflows/doc.yml

@@ -16,13 +16,13 @@ jobs:
       - uses: prefix-dev/[email protected]
         with: { pixi-version: v0.30.0 }
       - run: |
-          pixi run -e doc build-doc
+          pixi run -e dev build-doc
           touch doc/manual/generated/html/.nojekyll
       - name: detect broken links
-        run: pixi run -e doc test-doc-linkchecker
+        run: pixi run -e dev test-doc-linkchecker
       - uses: JamesIves/[email protected]
         with:
           branch: gh-pages
-          folder: doc/manual/generated/html/e-antic
+          folder: doc/manual/generated/html
           target-folder: docs
         if: ${{ github.event_name == 'push' }}

README.md

@@ -32,6 +32,22 @@ The dependencies are:
  - [Boost](https://www.boost.org/) for the C++ library
  - [cppyy](https://cppyy.readthedocs.io/en/latest/) for the Python wrapper
 
+## Usage
+
+We compute $a^2 - 2$ in the C++ interface where $a$ is a root of $x^3 - 3x + 1$.
+
+```cpp
+auto K = eantic::renf_class::make("x^3 - 3*x + 1", "x", "0.34 +/- .01");
+auto a = K->gen();
+auto b = a.pow(2) - 2;
+```
+
+Our [documentation](https://flatsurf.github.io/e-antic) has more details about
+[this example](https://flatsurf.github.io/e-antic/cxx_overview.html) and also
+shows you how to do the same computation with the [C
+interface](https://flatsurf.github.io/e-antic/c_overview.html) and the [Python
+interface](https://flatsurf.github.io/e-antic/python_overview.html).
+
 ## Build and Develop e-antic with pixi
 
 If you have cloned the source repository, make sure to pull in all the
@@ -162,10 +178,26 @@ the time of this writing.
 
 For more detailed but generic instructions please refer to the INSTALL file.
 
-## Installation
+## Feedback and Contributions
+
+If you have tried out e-antic, we are thrilled to learn about your experiences.
+If you ran into any problems or have suggestions for improvement, please
+[create an issue](https://github.com/flatsurf/e-antic/issues).
+
+If you want to contribute to e-antic, [pull
+requests](https://github.com/flatsurf/e-antic/pulls) are always welcome :heart:
+
+We are also happy to walk you through the process personally if you are unsure
+how to get started. Feel free to reach out in the [#flatsurf stream on
+Zulip](https://sagemath.zulipchat.com/#narrow/channel/271193-flatsurf) in any
+case.
+
+## License
 
-See [our documentation](https://flatsurf.github.io/e-antic/libeantic/#installation)
-for installation instructions.
+e-antic is free software: you can redistribute it and/or modify it under the
+terms of the GNU Lesser General Public License (LGPL) as published by the Free
+Software Foundation; either version 3.0 of the License, or (at your option) any
+later version. See https://www.gnu.org/licenses/.
 
 ## How to Cite this Project
 

doc/configure.ac

@@ -18,13 +18,9 @@ AC_PATH_PROG([SPHINXBUILD], [sphinx-build], [no])
 AS_IF([test x"$ac_cv_path_SPHINXBUILD" == x"no"], [AC_MSG_ERROR([sphinx-build could not be found. It is required to build the documentation. Use --without-doc to not build the documentation of e-antic.])])
 AC_SUBST([SPHINXBUILD], [$ac_cv_path_SPHINXBUILD])
 
-AC_PATH_PROG([STANDARDESE], [standardese], [no])
-AS_IF([test x"$ac_cv_path_STANDARDESE" == x"no"], [AC_MSG_ERROR([standardese could not be found. It is required to build the documentation. Use --without-doc to not build the documentation of e-antic.])])
-AC_SUBST([STANDARDESE], [$ac_cv_path_STANDARDESE])
-
-AC_PATH_PROG([MKDOCS], [mkdocs], [no])
-AS_IF([test x"$ac_cv_path_MKDOCS" == x"no"], [AC_MSG_ERROR([MkDocs could not be found. It is required to build the documentation. Use --without-doc to not build the documentation of e-antic.])])
-AC_SUBST([MKDOCS], [$ac_cv_path_MKDOCS])
+AC_PATH_PROG([DOXYGEN], [doxygen], [no])
+AS_IF([test x"$ac_cv_path_DOXYGEN" == x"no"], [AC_MSG_ERROR([doxygen could not be found. It is required to build the documentation. Use --without-doc to not build the documentation of e-antic.])])
+AC_SUBST([DOXYGEN], [$ac_cv_path_DOXYGEN])
 
 AC_CONFIG_FILES([Makefile manual/Makefile])