aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorlonkaars <loek@pipeframe.xyz>2024-04-14 14:43:33 +0200
committerlonkaars <loek@pipeframe.xyz>2024-04-14 14:43:33 +0200
commita24ebd2dce62255873ec204065262c8743245769 (patch)
tree13839d9b93aa9d3a3e90a24f12b3069e48785e33
parent898bc5d79c70c859d66b8c1548446c6e45302421 (diff)
fix source management in asciidoc
-rw-r--r--docs/.gitignore3
-rw-r--r--docs/Gemfile7
-rw-r--r--docs/makefile7
-rw-r--r--docs/plan.adoc37
-rw-r--r--docs/readme.md12
-rw-r--r--docs/share/footer.adoc4
-rw-r--r--docs/share/references.adoc5
-rw-r--r--docs/share/refs.bib191
8 files changed, 242 insertions, 24 deletions
diff --git a/docs/.gitignore b/docs/.gitignore
index 397e45c..a2f45c2 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,2 +1,5 @@
*.pdf
res
+
+# i know this is bad
+Gemfile.lock
diff --git a/docs/Gemfile b/docs/Gemfile
new file mode 100644
index 0000000..67cd54a
--- /dev/null
+++ b/docs/Gemfile
@@ -0,0 +1,7 @@
+ruby '~> 3.0'
+source 'https://rubygems.org'
+
+gem 'asciidoctor', '~> 2.0'
+gem 'asciidoctor-pdf', '~> 2.3'
+gem 'asciidoctor-bibtex', '~> 0.8.0'
+
diff --git a/docs/makefile b/docs/makefile
index 385ed09..cccc231 100644
--- a/docs/makefile
+++ b/docs/makefile
@@ -1,13 +1,16 @@
all: plan.pdf
-include font.mk
+# include font.mk
# PDFDEPS += $(ALL_FONTS)
PDFDEPS += ./theme.yml
+ASCIIDOCTOR_ARGS += --require asciidoctor-bibtex
+ASCIIDOCTOR_ARGS += --require asciidoctor-pdf
ASCIIDOCTOR_ARGS += --backend pdf
ASCIIDOCTOR_ARGS += --attribute pdf-theme=./theme.yml
# ASCIIDOCTOR_ARGS += --attribute pdf-fontsdir=./res/font
+ASCIIDOCTOR_ARGS += --attribute bibtex-file=./share/refs.bib
%.pdf: %.adoc $(PDFDEPS)
- asciidoctor --require asciidoctor-pdf $(ASCIIDOCTOR_ARGS) $<
+ asciidoctor $(ASCIIDOCTOR_ARGS) $<
diff --git a/docs/plan.adoc b/docs/plan.adoc
index 778506a..63df9a0 100644
--- a/docs/plan.adoc
+++ b/docs/plan.adoc
@@ -23,7 +23,7 @@ Monday afternoon. The goal is for teams to perform tasks related to electrical
engineering and computer science programs. The competitive element and
interaction with other groups are crucial. For the 19-20 introduction, the bomb
task was created, inspired by the game "Keep Talking and Nobody Explodes." A
-description of the game can be found on the website [1].
+description of the game can be found on the website cite:[Kee23].
Originally, the plan was to create a bomb that needs to be defused and a puzzle
box generating codes for defusing the bomb. A previous group successfully
@@ -329,9 +329,9 @@ discussed.
=== Version management
All source code developed during this project is kept under version control
-using the Git [2] version control system and is available online at GitHub [3].
-Each software component has a 3-digit version number following semantic
-versioning [4] conventions (major, minor, patch).
+using the Git cite:[gitscm] version control system and is available online at
+GitHub cite:[gitrepo]. Each software component has a 3-digit version number
+following semantic versioning cite:[semver] conventions (major, minor, patch).
This repository also utilizes Git submodules to track the versions of the
utilized libraries and SDKs. Submodules refer to commits, and can automatically
@@ -339,24 +339,25 @@ be initialized and managed using Git, so are not further specified in this
document.
All project documentation is realized using Microsoft Office products and is
-therefore stored in a SharePoint folder [5]. These documents use a simple
-2-digit (major, minor) version number system. The documents are published at
-the discretion of the authors, with each new version incrementing the minor
-version number. Major version number 0 is utilized for the document draft
-versions, while 1 is utilized for documents after the project goal is reached.
-A copy of all the documents is kept for each officially published version.
+therefore stored in a SharePoint folder cite:[sharepoint]. These documents use
+a simple 2-digit (major, minor) version number system. The documents are
+published at the discretion of the authors, with each new version incrementing
+the minor version number. Major version number 0 is utilized for the document
+draft versions, while 1 is utilized for documents after the project goal is
+reached. A copy of all the documents is kept for each officially published
+version.
== Planning
-This project utilizes GitHub Projects [6] to manage and allocate tasks to team
-members. GitHub Projects supports multiple workflows, but this project only
-follows the Kanban [7] workflow. Since the Kanban workflow does not require
-sprints, the project is divided into milestones. A milestone is considered
-complete once all tasks assigned to it are both marked as ‘complete’ and have
-been reviewed.
+This project utilizes GitHub Projects cite:[githubprojects] to manage and
+allocate tasks to team members. GitHub Projects supports multiple workflows,
+but this project only follows the Kanban cite:[atlassiankanban] workflow. Since
+the Kanban workflow does not require sprints, the project is divided into
+milestones. A milestone is considered complete once all tasks assigned to it
+are both marked as ‘complete’ and have been reviewed.
At the request of the stakeholders, time spent working on the project is
-tracked by each team member using Clockify [8].
+tracked by each team member using Clockify cite:[clockify].
[[fig:planning-condensed]]
.Condensed Gantt planning
@@ -381,5 +382,5 @@ The qualification phase (<<sec:phase-qualification>>) consists of validating
the results of the development phase, fixing issues when they are discovered,
and finalizing all project documentation.
-include::share/glossary.adoc[]
+include::share/footer.adoc[]
diff --git a/docs/readme.md b/docs/readme.md
index 262cac1..efcf30d 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -1,8 +1,9 @@
# docs
-This folder contains the project documentation in [asciidoc][asciidoc] format.
-A makefile is provided for easily compiling these documents into PDFs for
-submission.
+This folder contains the project documentation in [AsciiDoc][asciidoc] format.
+To compile the documents, make sure you have [Ruby][rubydl] and the
+dependencies installed by running the `bundle` command in this folder. A
+makefile is provided for convenience.
## TODO
@@ -17,7 +18,10 @@ submission.
- [x] section numbers (headings)
- [ ] requirements
- [x] figures
-- [ ] citations
+- [x] citations
- [ ] glossary
- [ ] PDF style
+[rubydl]: https://www.ruby-lang.org/en/documentation/installation/
+[asciidoc]: https://asciidoc.org/
+
diff --git a/docs/share/footer.adoc b/docs/share/footer.adoc
new file mode 100644
index 0000000..b3edec3
--- /dev/null
+++ b/docs/share/footer.adoc
@@ -0,0 +1,4 @@
+include::references.adoc[]
+
+include::glossary.adoc[]
+
diff --git a/docs/share/references.adoc b/docs/share/references.adoc
new file mode 100644
index 0000000..e475900
--- /dev/null
+++ b/docs/share/references.adoc
@@ -0,0 +1,5 @@
+[references]
+== References
+
+bibliography::[]
+
diff --git a/docs/share/refs.bib b/docs/share/refs.bib
new file mode 100644
index 0000000..f2cb813
--- /dev/null
+++ b/docs/share/refs.bib
@@ -0,0 +1,191 @@
+@online{githubprojects,
+ title = {About Projects - GitHub Docs},
+ url = {https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects},
+ msbib-accessed = {2024-02-15},
+ year = {2024},
+}
+
+@online{clockify,
+ title = {Clockify - The most popular free time tracker for teams},
+ url = {https://clockify.me/},
+ msbib-accessed = {2024-02-15},
+ year = {2024},
+}
+
+@online{gitscm,
+ title = {Git},
+ url = {https://git-scm.com/},
+ month = feb,
+ msbib-day = {15},
+ year = {2024},
+}
+
+@online{Kee23,
+ title = {Keep talking and nobody explodes - defuse a bomb with your friends.},
+ url = {https://keeptalkinggame.com/},
+ month = oct,
+ msbib-day = {10},
+ year = {2023},
+}
+
+@online{gitrepo,
+ author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas},
+ title = {lonkaars/puzzelbox: Avans Hogeschool project Puzzelbox},
+ url = {https://github.com/lonkaars/puzzelbox},
+ month = feb,
+ msbib-day = {15},
+ year = {2024},
+}
+
+@online{sharepoint,
+ author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas},
+ title = {PROJ-PUZZLE},
+ url = {https://avans-my.sharepoint.com/:f:/r/personal/tv_intanker_student_avans_nl/Documents/PROJ-PUZZLE?csf=1&web=1&e=wbKFig},
+ month = feb,
+ msbib-day = {15},
+ year = {2024},
+}
+
+@online{semver,
+ author = {Preston-Werner, Tom},
+ title = {Semantic Versioning 2.0.0},
+ url = {https://semver.org/},
+ month = jun,
+ msbib-day = {6},
+ year = {2023},
+}
+
+@online{atlassiankanban,
+ author = {Radigan, Dan},
+ title = {Kanban - A brief introduction},
+ url = {https://www.atlassian.com/agile/kanban},
+ msbib-accessed = {2024-02-15},
+ year = {2024},
+}
+
+@techreport{Bek23,
+ author = {Bekema, Frank and Gense, Jasper},
+ title = {Programma van Eisen Puzzel box},
+ year = {2023},
+}
+
+@techreport{styleguide,
+ author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas},
+ title = {Style guide},
+ location = {'s-Hertogenbosch},
+ publisher = {Avans University of Applied Sciences},
+ year = {2024},
+}
+
+@online{Wik22,
+ author = {Wikipedia-contributors},
+ title = {MOSCOW-Methode},
+ url = {https://nl.wikipedia.org/wiki/MoSCoW-methode},
+ month = apr,
+ msbib-day = {5},
+ year = {2022},
+}
+
+@online{rpicpu,
+ url = {https://www.raspberrypi.com/documentation/computers/processors.html},
+}
+
+@online{Ali24,
+ title = {A list of open-source C++ libraries},
+ url = {https://en.cppreference.com/w/cpp/links/libs},
+ msbib-accessed = {2024-02-25},
+}
+
+@online{Boo24,
+ url = {https://www.boost.org/doc/libs/1_75_0/libs/test/doc/html/index.html},
+ msbib-accessed = {2024-02-28},
+}
+
+@online{Git24,
+ title = {GitHub - boostorg/test: The reference C++ unit testing framework (TDD, xUnit, C++03/11/14/17).},
+ url = {https://github.com/boostorg/test},
+ msbib-accessed = {2024-02-28},
+}
+
+@online{Neo,
+ title = {Neotrellis},
+ url = {https://learn.adafruit.com/adafruit-neotrellis/overview},
+}
+
+@techreport{rp2040ds,
+ title = {RP2040 Datasheet},
+ publisher = {Raspberry Pi Ltd},
+ year = {2024},
+}
+
+@online{Cat24,
+ author = {Catchorg},
+ title = {Github - catchorg/Catch2: A modern, C++-native, test framework for unit-tests.},
+ msbib-accessed = {2024-02-25},
+}
+
+@online{Cpp24,
+ author = {Cpputest},
+ title = {Github - cpputest/cpputest: CppUTest unit testing and mocking framework for C/C++.},
+ url = {https://github.com/cpputest/cpputest},
+ msbib-accessed = {2024-02-25},
+}
+
+@online{Doc24,
+ author = {Doctest},
+ title = {Github - doctest/doctest: The fastest feature-rich C++11/14/17/20/23 single-header testing framework.},
+ url = {https://github.com/doctest/doctest},
+ msbib-accessed = {2024-02-25},
+}
+
+@online{goo24,
+ author = {google},
+ title = {GitHub - google/googletest: GoogleTest - Google Testing and Mocking Framework.},
+ url = {https://github.com/google/googletest},
+ msbib-accessed = {2024-02-28},
+}
+
+@online{Joh21,
+ author = {Johnston, P.},
+ title = {Embedded systems testing resources},
+ url = {https://embeddedartistry.com/blog/2018/10/18/embedded-systems-testing-resources/},
+ month = jun,
+ msbib-day = {10},
+ msbib-accessed = {2024-02-25},
+ year = {2021},
+}
+
+@techreport{research,
+ author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas},
+ title = {Research Document},
+ location = {'s-Hertogenbosch},
+ publisher = {Avans University of Applied Sciences},
+ year = {2024},
+}
+
+@techreport{2021_design,
+ author = {Creemers, Merel and van Wiechen, Joost and Lengowski, Vincent and Maas, Justin},
+ title = {Ontwerpdocument},
+ language = {dutch},
+ location = {'s-Hertogenbosch},
+ publisher = {Avans University of Applied Sciences},
+ year = {2021},
+}
+
+@techreport{2122_handover,
+ author = {van Gastel, Lucas and de Bruin, Julian and Rockx, Toon and van Kuijk, Alex and Baars, Jef},
+ title = {Overdrachtsdocument},
+ language = {dutch},
+ location = {'s-Hertogenbosch},
+ publisher = {Avans University of Applied Sciences},
+ year = {2022},
+}
+
+@techreport{2122_design,
+ author = {van Gastel, Lucas and de Bruin, Julian and Rockx, Toon and van Kuijk, Alex and Baars, Jef},
+ title = {Design document},
+ language = {dutch},
+ location = {'s-Hertogenbosch},
+ publisher = {Avans University of Applied Sciences},
+ year = {2022},
+}