Generating an mdBook-based variant of the SRS - UPDATED

BilalM04 commented 5 days ago

This PR is an extension of #3814. Please read https://github.com/JacquesCarette/Drasil/pull/3814#issue-2365220779 before reading this PR.

Contributes to #3722 Closes #3827

Updates / New Additions

Refactored how the sections are separated (more info below).
Generated a SUMMARY.md file, which is used for the side panel in mdBook.
Generated a book.toml config file, similar to how the CSS is currently generated.
Generated a title page file (title.md)
Separated into two new SRS formats: Markdown and mdBook (more info below).
Got the cross-file references working for the mdBook format.
Fixed minor issues in expression printing.
Generated SRS for all examples and updated stable. I roughly scanned over and ran all of them. They seem to all be working and rendering as desired.
Added mdBook installation instructions to the New Workspace Setup wiki.
Added makefile targets to build and run server of mdBook projects.

To run the mdBook projects, go to the build/example_name/SRS/mdBook directory and enter mdbook serve --open in terminal to run a local server and view the SRS.

These mdBook SRSs can also be hosted on the website. By running mdbook build in terminal, a book directory is created. which contains all the HTML, CSS, and JavaScript files.

Refactoring the Separation of Sections

Please read https://github.com/JacquesCarette/Drasil/discussions/3796#discussion-6809343 to understand how SRS generation currently works in Drasil. To summarize, here is the main info:

The format specific gen functions receive a single Document, which contains all the SRS details. The Document it receives is in the format of the data type defined in Language.Drasil.Document, where the SRS contents is represented through [Section]. The format specific gen functions, using the makeDocument function, then convert it to the Document data type defined in Language.Drasil.Printing.LayoutObj, where the SRS content is represented through [LayoutObj]. The SRS printers then render these LayoutObj's into a single Doc.

In #3814, the SRS was separated into separate files once it became in the format of the Document data type defined in Language.Drasil.Printing.LayoutObj. I found this to be quite a late stage to be separating, as it was hard to distinguish where each LayoutObj belonged. Additionally, the Document type is implicitly assuming a single file is being generated. Instead I created a new data type Project and File:

https://github.com/JacquesCarette/Drasil/blob/5f9ba9280a05c8eca11af14c06ef3957e1fdc64f/code/drasil-printers/lib/Language/Drasil/Printing/LayoutObj.hs#L14-L16

The Project type contains a RefMap, which maps reference anchor ids to the Filename of the File that contains them. This map is then used when rendering references in mdBook.

Unlike in #3814, where the given SRS gets converted to a Document type, it now gets converted to a Project using the new makeProject function.

Markdown vs mdBook

I created two new SRS formats. The first being MDBook which generates the mdBook project. The other being Markdown which generates a single-page SRS in Markdown which can be rendered directly in the GitHub repo. I spoke to @balacij about this, and he seems to agree that having the two separate formats is beneficial. @smiths and @JacquesCarette, what are your thoughts?

The Markdown format is not complete. Currently it renders with the exact same syntax as mdBook; however, there are slight differences in syntax between the two. I will not be addressing that issue in this PR/branch as I believe creating a separate issue and branch after this is merged is the best approach. Addressing this Markdown format will also help with the issues in the JSON format, as the two formats use the same "flavour" of Markdown.

Next Steps

Work with @balacij to get the required assets into the generated src directory and host the mdBook SRSs.
Address the issues in the Markdown format.

samm82 commented 4 days ago

When trying to checkout this branch, the wiki bug from #3793 seems to reappear - any ideas why? @BilalM04 @balacij

samcr@Apex MINGW64 ~/Desktop/Drasil/code (main)
$ git checkout mdBookPrinterTest 
error: invalid path 'wiki/Attributes-and-Chunks:-Meeting-June-7th,-2023.md'

samm82 commented 4 days ago

To run the mdBook projects, go to the build/example_name/SRS/mdBook directory and enter mdbook serve --open in terminal to run a local server and view the SRS.

Could we also generate a Makefile to handle this? Idk how involved that would be 😅

EDIT: I think mdbook installation instructions should be added to the wiki, even if it is just a pointer to the installation documentation like you do on your repo.

BilalM04 commented 4 days ago

@samm82 the invalid path error is likely due to the fix not being on this branch. I just merged main into the mdBookPrinterTest branch, which should hopefully resolve the issue.

samm82 commented 4 days ago

I needed to git fetch in order to actually get the new changes locally, as opposed to the git checkout <branch>; git pull workflow I'm used to (just thought I'd share my silliness). I'm able to switch over to the branch now! 🙃

BilalM04 commented 14 hours ago

From @samm82's suggestions in https://github.com/JacquesCarette/Drasil/pull/3823#issuecomment-2197367526, I added the mdBook installation instructions to the New Workspace Setup wiki in https://github.com/JacquesCarette/Drasil/pull/3823/commits/b9b2047435320e126c2812f58fa152e1042736af, and added makefile targets for mdBook in https://github.com/JacquesCarette/Drasil/pull/3823/commits/df11d396354854a16b70cb3970e65d65c85f8ebf. @balacij suggested to keep these additions within this PR.

Added makefile targets:

make mdbook_build - Build all generated mdBook projects.
make X_mdbook_build - Build the mdBook SRS of an individual example.
make X_mdbook_server - Launch local server for the mdBook SRS of an individual example.

samm82 commented 14 hours ago

Should these be renamed to mdbook (all lowercase)? That's what the command is, which is what I assumed the make rule would be called (if there's a reason for using mdBook, I'm sure that's fine too)!

BilalM04 commented 14 hours ago

I used mdBook as that is how it is capitalized in the mdBook documentation. However, I agree it should be renamed to mdbook in the makefile, as the actual command is all lower case. Additionally it will now be consistent with all the other targets (which are also all lower case).

JacquesCarette / Drasil