From c91bc43854f92d4cb810153a16a503d709ccbdab Mon Sep 17 00:00:00 2001 From: Oliver Ruebel Date: Wed, 28 Aug 2024 16:36:42 -0700 Subject: [PATCH] Fix linking to the requirements (#79) * Fix #78 Fix linking to the requirements * Create separate mainpage for the docs and replace @ with \ for consistency * Spell fix and add missing Doxyfile.in changes * Fix missing anchors * Change legal heading * Update README.md Co-authored-by: Steph Prince <40640337+stephprince@users.noreply.github.com> --------- Co-authored-by: Steph Prince <40640337+stephprince@users.noreply.github.com> --- README.md | 23 +++------- docs/Doxyfile.in | 5 +-- docs/pages/0_mainpage.dox | 66 ++++++++++++++++++++++++++++ docs/pages/1_userdocs.dox | 6 +-- docs/pages/2_devdocs.dox | 14 +++--- docs/pages/devdocs/copyright.dox | 2 +- docs/pages/devdocs/documentation.dox | 8 ++-- docs/pages/devdocs/install.dox | 19 ++++++-- docs/pages/devdocs/license.dox | 2 +- docs/pages/devdocs/testing.dox | 4 +- docs/pages/userdocs/hdf5io.dox | 4 +- docs/pages/userdocs/install.dox | 14 +++--- 12 files changed, 119 insertions(+), 48 deletions(-) create mode 100644 docs/pages/0_mainpage.dox diff --git a/README.md b/README.md index e29a5f1f..249d6d96 100644 --- a/README.md +++ b/README.md @@ -20,25 +20,14 @@ Below is a high-level overview of the project structure and capabilities we are ![Project Overview](resources/images/aqnwb_objective_500px.png) - - -## Requirements - -- **Minimum Requirements:** - - A C++17-compliant compiler - - [CMake >= 3.15](https://cmake.org) - - [HDF5 >= 1.10](https://github.com/HDFGroup/hdf5) - - [Boost](https://www.boost.org/) -- **Documentation:** Additional requirements for building the documentation (optional) - - [Doxygen](https://www.doxygen.nl/) - - [Graphviz](https://graphviz.org/) -- **For Developers:** Additional requirements for developers (mode `dev`) - - cppcheck - - clang-format (optional, required for ``target=format-check``, ``target=format-fix``) - - codespell (optional, required for ``target=spell-check``, ``target=spell-fix``) - ## Installation See the [AqNWB Documentation](https://neurodatawithoutborders.github.io/aqnwb/) for installation and integration instructions. * [User Installation](https://neurodatawithoutborders.github.io/aqnwb/install_page.html) * [Developer Installation](https://neurodatawithoutborders.github.io/aqnwb/dev_install_page.html) + +## Contributing and Legal + +For more information about the license, contributing guidelines, code of conduct +and other relevant documentation for developers please see the +[Developer Documentation](https://neurodatawithoutborders.github.io/aqnwb/devdocs.html). \ No newline at end of file diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 23395980..36f9eebb 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -7,7 +7,7 @@ PROJECT_NAME = "@PROJECT_NAME@" PROJECT_NUMBER = "@PROJECT_VERSION@" # Add sources -INPUT = "@PROJECT_SOURCE_DIR@/README.md" "@PROJECT_SOURCE_DIR@/src" "@PROJECT_SOURCE_DIR@/docs/pages" +INPUT = "@PROJECT_SOURCE_DIR@/src" "@PROJECT_SOURCE_DIR@/docs/pages" EXAMPLE_PATH = "@PROJECT_SOURCE_DIR@/tests" "@PROJECT_SOURCE_DIR@/.github/CODE_OF_CONDUCT.md" "@PROJECT_SOURCE_DIR@/Legal.txt" "@PROJECT_SOURCE_DIR@/LICENSE" IMAGE_PATH = "@PROJECT_SOURCE_DIR@/resources/images" EXTRACT_ALL = YES @@ -17,9 +17,6 @@ OUTPUT_DIRECTORY = "@DOXYGEN_OUTPUT_DIRECTORY@" # Enable Markdown support MARKDOWN_SUPPORT = YES -# Use the README as a main page -USE_MDFILE_AS_MAINPAGE = "@PROJECT_SOURCE_DIR@/README.md" - # set relative include paths FULL_PATH_NAMES = YES STRIP_FROM_PATH = "@PROJECT_SOURCE_DIR@/include" "@PROJECT_SOURCE_DIR@" diff --git a/docs/pages/0_mainpage.dox b/docs/pages/0_mainpage.dox new file mode 100644 index 00000000..697f4fec --- /dev/null +++ b/docs/pages/0_mainpage.dox @@ -0,0 +1,66 @@ +/** + * \mainpage Overview + * + * \tableofcontents + * + * AqNWB is a C++ API for acquiring neurophysiological data directly into the NWB (Neurodata Without Borders) format. + * Our goal is to provide a lightweight API to integrate with existing acquisition systems. + * Below is a high-level overview of the project structure and capabilities we are targeting: + * + * \image html resources/images/aqnwb_objective.png "Project Overview" width=500px + * + * \section Status + * + * **AqNWB is currently under active development and should not yet be used in practice.** + * + * \htmlonly + *

+ * + * Unit tests + * + * + * Codespell + * + * + * Lint + * + * + * Docs build + * + *

+ *

+ * + * Source + * + * + * Code Stats + * + * + * Online Docs + * + *

+ * \endhtmlonly + * + * \section mainpage_installation Installation + * + * - \ref user_install_page "User Installation" + * - \ref dev_install_page "Developer Installation" + * + * \section mainpage_navigation Navigating the Documentation + * + * The documentation is divided into the following main sections: + * + * - \ref userdocs : This section is for users who want to use AqNWB in their software project, e.g., to + * integrate NWB with an acquisition system. + * - \ref devdocs : This section is for developers and community members who would like to + * contributed to the development of AqNWB. + * - **API Reference:** The [Namespaces](namespaces.html), [Classes](annotated.html), and [Files](files.html) + * sections are autogenerated from the AqNWB source code using Doxygen, providing a detailed reference of all + * classes, namespaces, files, functions, etc. defined by AqNWB. + * + * \section mainpage_contributing Legal + * + * - \ref code_of_conduct_page + * - \ref license_page + * - \ref copyright_page + */ diff --git a/docs/pages/1_userdocs.dox b/docs/pages/1_userdocs.dox index c6a90b61..20ebced1 100644 --- a/docs/pages/1_userdocs.dox +++ b/docs/pages/1_userdocs.dox @@ -1,9 +1,9 @@ /** - * @page userdocs For Users + * \page userdocs For Users * * This documentation is intended for users of AqNWB, e.g., developers seeking to integrate NWB * with a particular data acquisition software via AqNWB. * - * - @subpage install_page - * - @subpage hdf5io + * - \subpage user_install_page + * - \subpage hdf5io */ diff --git a/docs/pages/2_devdocs.dox b/docs/pages/2_devdocs.dox index 7b868d38..f8a9d477 100644 --- a/docs/pages/2_devdocs.dox +++ b/docs/pages/2_devdocs.dox @@ -1,13 +1,13 @@ /** - * @page devdocs For Developers + * \page devdocs For Developers * * This documentation is intended for developers of AqNWB. * - * - @subpage dev_install_page - * - @subpage testing - * - @subpage dev_docs_page - * - @subpage code_of_conduct_page - * - @subpage license_page - * - @subpage copyright_page + * - \subpage dev_install_page + * - \subpage testing + * - \subpage dev_docs_page + * - \subpage code_of_conduct_page + * - \subpage license_page + * - \subpage copyright_page * */ diff --git a/docs/pages/devdocs/copyright.dox b/docs/pages/devdocs/copyright.dox index 8f6532be..f84e419b 100644 --- a/docs/pages/devdocs/copyright.dox +++ b/docs/pages/devdocs/copyright.dox @@ -1,5 +1,5 @@ /** - * @page copyright_page Copyright + * \page copyright_page Copyright * * \include Legal.txt */ diff --git a/docs/pages/devdocs/documentation.dox b/docs/pages/devdocs/documentation.dox index 0d33aa60..8a026761 100644 --- a/docs/pages/devdocs/documentation.dox +++ b/docs/pages/devdocs/documentation.dox @@ -1,5 +1,7 @@ /** - * @page dev_docs_page Documentation + * \page dev_docs_page Documentation + * + * \tableofcontents * * AqNWB uses [Doxygen](https://www.doxygen.nl/) with [Graphviz](https://graphviz.org/) for * documentation. The ``cmake`` related instructions on this page follow the @@ -27,12 +29,12 @@ * \par **docs/pages/userdocs/mypage.dox** * \code{.sh} * /** - * * @page mypage My New Page + * * \page mypage My New Page * * * */ * \endcode * - * and add a corresponding ``- @subpage mypage`` entry to the page listing of the ``docs/pages/1_userdocs.dox`` + * and add a corresponding ``- \subpage mypage`` entry to the page listing of the ``docs/pages/1_userdocs.dox`` * file. Note, the ``subpage`` command uses the label of the page (here ``mypage``) and not the name of the file. * * Similarly, we can add pages to the \ref devdocs docs by adding a new ``.dox`` file to the ``docs/pages/devdocs`` diff --git a/docs/pages/devdocs/install.dox b/docs/pages/devdocs/install.dox index ac96f398..f4816b9d 100644 --- a/docs/pages/devdocs/install.dox +++ b/docs/pages/devdocs/install.dox @@ -1,11 +1,24 @@ /** - * @page dev_install_page Installation & Setup + * \page dev_install_page Installation & Setup + * + * \tableofcontents * * \section dev_requirements_sec Requirements * * Please ensure that the required libraries described in the - * \ref requirements "Requirements" section are installed. For developers we recommend - * to also install optional dependencies to ease development. + * \ref user_requirements_sec "User Requirements" section are installed. + * + * For developers we also recommend to install the following optional command line tools used for + * generating the documentation, for code quality checks, and for debugging. + * + * - **Documentation:** Additional requirements for building the documentation (optional) + * - [Doxygen](https://www.doxygen.nl/) + * - [Graphviz](https://graphviz.org/) + * - **Code checks:** Additional command line tools used in developer mode `dev` + * - cppcheck + * - clang-format (optional, required for ``target=format-check``, ``target=format-fix``) + * - codespell (optional, required for ``target=spell-check``, ``target=spell-fix``) + * * * \section devbuild_sec Developer Build * diff --git a/docs/pages/devdocs/license.dox b/docs/pages/devdocs/license.dox index 7b57b4a5..a18d333f 100644 --- a/docs/pages/devdocs/license.dox +++ b/docs/pages/devdocs/license.dox @@ -1,5 +1,5 @@ /** - * @page license_page License + * \page license_page License * * \include LICENSE */ diff --git a/docs/pages/devdocs/testing.dox b/docs/pages/devdocs/testing.dox index 28244619..cfd81240 100644 --- a/docs/pages/devdocs/testing.dox +++ b/docs/pages/devdocs/testing.dox @@ -1,5 +1,7 @@ /** - * @page testing Testing + * \page testing Testing + * + * \tableofcontents * * \section testing_unit Unit Tests * diff --git a/docs/pages/userdocs/hdf5io.dox b/docs/pages/userdocs/hdf5io.dox index acd7b715..263e0f3b 100644 --- a/docs/pages/userdocs/hdf5io.dox +++ b/docs/pages/userdocs/hdf5io.dox @@ -1,5 +1,7 @@ /** - * @page hdf5io HDF5 I/O + * \page hdf5io HDF5 I/O + * + * \tableofcontents * * \section hdf5io_chunking Chunking * diff --git a/docs/pages/userdocs/install.dox b/docs/pages/userdocs/install.dox index 8fc41c83..28f42056 100644 --- a/docs/pages/userdocs/install.dox +++ b/docs/pages/userdocs/install.dox @@ -1,10 +1,14 @@ /** - * @page install_page Installing AqNWB + * \page user_install_page Installing AqNWB * * \section user_requirements_sec Requirements * - * Please ensure that the required libraries described in the - * \ref requirements "Requirements" section are installed. + * Please ensure that the required libraries are installed. + * + * - A C++17-compliant compiler + * - [CMake >= 3.15](https://cmake.org) + * - [HDF5 >= 1.10](https://github.com/HDFGroup/hdf5) + * - [Boost](https://www.boost.org/) * * \section userbuild_build_sec Build * @@ -31,7 +35,3 @@ * */ - - - - */