docs: support for Bibtex citations (#500)

Author: benthevining

.pre-commit-config.yaml

@@ -98,7 +98,7 @@ repos:
 
     # C++ formatting & linting
 - repo: https://github.com/pre-commit/mirrors-clang-format
-  rev: v22.1.0
+  rev: v22.1.1
   hooks:
   - id: clang-format
     exclude_types: [json]
@@ -138,7 +138,7 @@ repos:
   - id: pyupgrade
 
 - repo: https://github.com/psf/black-pre-commit-mirror
-  rev: 26.3.0
+  rev: 26.3.1
   hooks:
   - id: black
 
@@ -167,6 +167,13 @@ repos:
     files: .github/workflows/
     types: [yaml]
 
+  # format .bib file
+- repo: https://github.com/FlamingTempura/bibtex-tidy
+  rev: v1.14.0
+  hooks:
+  - id: bibtex-tidy
+    args: [--modify, --curly, --numeric, --months, --space=2, --blank-lines, --duplicates, --merge=combine, --strip-enclosing-braces, --drop-all-caps, --sort-fields, --no-strip-comments, --no-trailing-commas, --remove-empty-fields, --wrap=80]
+
     # general
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v6.0.0

docs/CMakeLists.txt

@@ -21,17 +21,21 @@ endif ()
 include ("${CMAKE_CURRENT_LIST_DIR}/DoxygenSettings.cmake")
 
 # inputs & filepaths
-set (DOXYGEN_OUTPUT_DIRECTORY "${BenBot_BINARY_DIR}/generated-docs")
 set (DOXYGEN_USE_MDFILE_AS_MAINPAGE "${BenBot_SOURCE_DIR}/README.md")
 set (DOXYGEN_LAYOUT_FILE "${CMAKE_CURRENT_LIST_DIR}/DoxygenLayout.xml")
+set (DOXYGEN_CITE_BIB_FILES "${CMAKE_CURRENT_SOURCE_DIR}/references.bib")
+
 set (DOXYGEN_FILE_PATTERNS *.hpp)
 set (DOXYGEN_INCLUDE_FILE_PATTERNS *.hpp)
+
 set (DOXYGEN_STRIP_FROM_PATH "${BenBot_SOURCE_DIR}")
 set (DOXYGEN_STRIP_FROM_INC_PATH
      "${BenBot_SOURCE_DIR}/libchess/include" "${BenBot_SOURCE_DIR}/libbenbot/include"
      "${BenBot_SOURCE_DIR}/ben-bot/include" "${BenBot_SOURCE_DIR}/ben-bot/resources/include"
 )
 
+set (DOXYGEN_OUTPUT_DIRECTORY "${BenBot_BINARY_DIR}/generated-docs")
+
 #
 
 get_target_property (libutil_headers ben_bot::libutil HEADER_SET)
@@ -42,6 +46,7 @@ get_target_property (resource_headers ben_bot::resources HEADER_SET)
 doxygen_add_docs (
     ben_bot_docs
     "${DOXYGEN_LAYOUT_FILE}"
+    "${DOXYGEN_CITE_BIB_FILES}"
     "${DOXYGEN_USE_MDFILE_AS_MAINPAGE}"
     "${CMAKE_CURRENT_LIST_DIR}/uci-spec.md"
     "${CMAKE_CURRENT_LIST_DIR}/top-level-groups.txt"

docs/references.bib

@@ -0,0 +1,9 @@
+@misc{Edwards_1994,
+  author        = {Edwards, Steven J.},
+  year          = 1994,
+  month         = dec,
+  journal       = {Standard: Portable Game Notation Specification and Implementation Guide},
+  url           = {
+    https://ia902908.us.archive.org/26/items/pgn-standard-1994-03-12/PGN_standard_1994-03-12.txt
+  },
+}

libchess/include/libchess/notation/PGN.hpp

@@ -13,7 +13,7 @@
  */
 
 /** @file
-    This file provides functions for parsing and writing PGN files.
+    This file provides functions for parsing and writing PGN @cite Edwards_1994 files.
     @ingroup notation
  */
 
@@ -35,7 +35,7 @@ namespace chess::notation {
 using game::Position;
 using std::string;
 
-/** PGN NAG glyphs are represented by their numeric codes.
+/** PGN @cite Edwards_1994 NAG glyphs are represented by their numeric codes.
     This enumeration lists many of the standard NAGs (but not all of them).
 
     @ingroup notation
@@ -127,7 +127,7 @@ struct [[nodiscard]] GameRecord final {
     [[nodiscard]] auto get_final_position() const -> Position;
 };
 
-/** Parses the text of a PGN file into a GameRecord object.
+/** Parses the text of a PGN @cite Edwards_1994 file into a GameRecord object.
 
     If the input string cannot be parsed correctly, returns an explanatory error string.
 
@@ -151,7 +151,7 @@ struct [[nodiscard]] GameRecord final {
 [[nodiscard]] auto parse_all_pgns(std::string_view fileContent)
     -> std::vector<GameRecord>;
 
-/** Creates a PGN string from the given game record.
+/** Creates a PGN @cite Edwards_1994 string from the given game record.
 
     @param game The game record to serialize.