soargroup / soargroup.github.io Goto Github PK

View Code? Open in Web Editor NEW

3.0 5.0 1.0 11.24 MB

Soar's website: documentation, news, announcements, links, etc.

Home Page: http://soar.eecs.umich.edu/

License: Other

HTML 77.30% Python 22.70%

cognitive-architecture documentation soar

soargroup.github.io's Introduction

Soar Website

⚠️⚠️⚠️ WORK IN PROGRESS ⚠️⚠️⚠️

This repository contains the source for the (new as of 2024) homepage for the Soar cognitive architecture, including source for the PDF's distributed with Soar.

The website is not yet fully migrated from the old site, and is still under construction.

The site is built using the MkDocs, a static site generator that uses Markdown files to generate a website. The theme is Material for MkDocs.

Setup/Running

python -m venv
source venv/bin/activate (or venv\Scripts\Activate on Windows)
pip install -r requirements.txt
mkdocs serve

Deployment

The site is deployed to GitHub Pages automatically as long as the build workflows don't fail.

Updates for New Soar Versions

Update the soar_version variable in mkdocs.yml.
Add announcement with link to docs/index.md.
Run the link-checker (manually triggered GH action workflow) to ensure all new release artifact links are valid.

soargroup.github.io's People

Contributors

Stargazers

Watchers

Forkers

moschmdt

soargroup.github.io's Issues

migrate workshop tutorial pages

One using LEGO MINDSTORMS is here: https://docs.google.com/document/d/1o9cWNXP0AgLJzQmlCPAdEuyOAd7NEor-ECX9C724lwE/edit. MINDSTORMS have been discontinued, unfortunately, but I think the tutorial is still valuable.

2019 workshop tutorials: https://web.archive.org/web/20230616111252/https://soar.eecs.umich.edu/tutorial/

Figure 6.1 seems to be missing

I'm not sure if more figures are missing, but when reading https://soar.eecs.umich.edu/soar_manual/06_SemanticMemory/, I noticed that figure 6.1 was not visible at all on the website while it is visible in the PDF

migrate Intro to the Soar Debugger page

Original page is here: https://web.archive.org/web/20230324032250/https://soar.eecs.umich.edu/articles/articles/faqs-and-guides/69-intro-to-the-soar-debugger

where to put binary assets

We have:

several GB of workshop presentations
the tutorials (these are in another GH repo, so we can link them there for now)
probably 100 MB of publications

I like keeping this repository light, so I'm inclined to keep them out of here. I'm thinking another repository dedicated to binary assets would be ideal.

Link to or migrate old files on SourceForge

Old versions of Soar and its utilities are up on SourceForge:
https://sourceforge.net/projects/soar/files/

Related: #11

Generate Soar programming reference from Doxygen comments and host here

Particularly an SML programming reference would be very helpful, since SWIG ignores Doxygen comments, and Python/Java, etc. developers are mostly flying blind. Whenever I need to understand something about the SML API, I search through Soar's C++ code for the original definition and read the comments there.

review of tutorial required to accept as canonical version

Remaining work listed in #12:

Copy images with annotations from Word document and replace automatically extracted images.
Format Markdown according to lint requirements
Review against Word versions.

review of manual required to accept as canonical edition

From #3:

The following chapters should be very close to the original version:

Chapter 1: Introduction
Chapter 2: The Soar Architecture
Chapter 3: Soar Syntax
Chapter 9: Soar User Interface
For chapter 9 I decided to link to the CLI documentation that is included in the PDF anyways. A pandoc filter, cf. path_filter.lua, is used to keep the links inside the conversion from multiple Markdown files to a single PDF document valid. Unfortunately, this requires that links to other parts of the Soar manual must include a section reference.

Unfortunately, I did not have time to go through the other chapters and compare them very closely to the manual about formatting and completeness.

Missing character in Soar manual PDF generation

Generating the PDF of the Soar manual results in multiple missing character errors:

[WARNING] Missing character: There is no  (U+0088) (U+0088) in font [lmroman12-regular]:+tlig;!

manual images unusable in dark mode

For example:

SVG can have CSS in it, so it is possible to change the colors based on whether the user has dark mode activated or not.

For now, users can just switch to light mode to view the images.

Add workshop section

Add a new workshop section to collect schedules and materials for all workshops. We can start by adding the materials collected this year!

Related: #11, #17