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 <[email protected]> --------- Co-authored-by: Steph Prince <[email protected]>
NeurodataWithoutBorders · Aug 28, 2024 · c91bc43 · c91bc43
1 parent 603c8ed
commit c91bc43
Show file tree

Hide file tree

Showing 12 changed files with 119 additions and 48 deletions.
diff --git 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)
 
-
-<a id="requirements"></a>
-## 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).
diff --git 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
@@ -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
+ * <p>
+ * <a href="https://github.com/NeurodataWithoutBorders/aqnwb/actions/workflows/tests.yml">
+ *     <img src="https://github.com/NeurodataWithoutBorders/aqnwb/actions/workflows/tests.yml/badge.svg" alt="Unit tests">
+ * </a>
+ * <a href="https://github.com/NeurodataWithoutBorders/aqnwb/actions/workflows/codespell.yml">
+ *     <img src="https://github.com/NeurodataWithoutBorders/aqnwb/actions/workflows/codespell.yml/badge.svg" alt="Codespell">
+ * </a>
+ * <a href="https://github.com/NeurodataWithoutBorders/aqnwb/actions/workflows/lint.yml">
+ *     <img src="https://github.com/NeurodataWithoutBorders/aqnwb/actions/workflows/lint.yml/badge.svg" alt="Lint">
+ * </a>
+ * <a href="https://github.com/NeurodataWithoutBorders/aqnwb/actions/workflows/doxygen-gh-pages.yml">
+ *     <img src="https://github.com/NeurodataWithoutBorders/aqnwb/actions/workflows/doxygen-gh-pages.yml/badge.svg" alt="Docs build">
+ * </a>
+ * </p>
+ * <p>
+  * <a href="https://github.com/NeurodataWithoutBorders/aqnwb">
+ *     <img src="https://img.shields.io/badge/AqNWB-Source-8A2BE2?style=flat" alt="Source">
+ * </a>
+ * <a href="https://nwb-overview.readthedocs.io/en/latest/nwb-project-analytics/docs/source/code_stat_pages/AqNWB_stats.html">
+ *     <img src="https://img.shields.io/badge/AqNWB-Code%20Statistics-8A2BE2?style=flat" alt="Code Stats">
+ * </a>
+  * <a href="https://neurodatawithoutborders.github.io/aqnwb/">
+ *     <img src="https://img.shields.io/badge/AqNWB-Online Docs-8A2BE2?style=flat" alt="Online Docs">
+ * </a>
+ * </p>
+ * \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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 @@
  *
  */
 
-
-
-
- */