From 31e6c2d099af1625250bb773046734beddbe45cc Mon Sep 17 00:00:00 2001 From: Tony Bark Date: Mon, 9 Jan 2023 15:44:41 -0500 Subject: [PATCH] WIP documentation book --- .github/workflows/book.yml | 26 +++++ .github/workflows/publish.yml | 30 ++++++ .gitignore | 92 ++++++++++++++++-- README.md | 8 +- docs/.vscode/settings.json | 4 + docs/.vscode/tasks.json | 25 +++++ docs/book.toml | 17 ++++ docs/custom.css | 3 + docs/src/README.md | 9 ++ docs/src/SUMMARY.md | 14 +++ docs/src/changelog.md | 23 +++++ docs/src/design/filesystem.md | 3 + docs/src/design/interfaces.md | 29 ++++++ docs/src/design/translations.md | 3 + docs/src/nethington/compliance.md | 7 ++ {assets => docs/src/static/imgs}/logo.png | Bin {assets => docs/src/static/imgs}/logo.svg | 0 .../src/static/imgs}/screenshot.png | Bin .../src/static/imgs}/social-preview.png | Bin .../src/static/imgs}/social-preview.xcf | Bin 20 files changed, 281 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/book.yml create mode 100644 .github/workflows/publish.yml create mode 100644 docs/.vscode/settings.json create mode 100644 docs/.vscode/tasks.json create mode 100644 docs/book.toml create mode 100644 docs/custom.css create mode 100644 docs/src/README.md create mode 100644 docs/src/SUMMARY.md create mode 100644 docs/src/changelog.md create mode 100644 docs/src/design/filesystem.md create mode 100644 docs/src/design/interfaces.md create mode 100644 docs/src/design/translations.md create mode 100644 docs/src/nethington/compliance.md rename {assets => docs/src/static/imgs}/logo.png (100%) rename {assets => docs/src/static/imgs}/logo.svg (100%) rename {assets => docs/src/static/imgs}/screenshot.png (100%) rename {assets => docs/src/static/imgs}/social-preview.png (100%) rename {assets => docs/src/static/imgs}/social-preview.xcf (100%) diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml new file mode 100644 index 0000000..42c6ab0 --- /dev/null +++ b/.github/workflows/book.yml @@ -0,0 +1,26 @@ +name: Build + +on: + schedule: + - cron: "0 0 * * 0" + push: + branches: [main, publish] + +jobs: + build: + timeout-minutes: 15 + continue-on-error: true + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [windows-latest, ubuntu-latest, macOS-latest] + steps: + - uses: actions/checkout@v2 + + - name: Setup + uses: peaceiris/actions-mdbook@v1 + with: + mdbook-version: "latest" + + - name: Build + run: mdbook build ./docs diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..3b08bdc --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,30 @@ +name: Publish + +on: + schedule: + - cron: "0 0 1 * *" + push: + branches: [main] + +jobs: + deploy: + timeout-minutes: 15 + continue-on-error: true + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + + - name: Setup + uses: peaceiris/actions-mdbook@v1 + with: + mdbook-version: "latest" + + - name: Build + run: mdbook build ./docs + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + cname: tomas.tonybark.com + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/book diff --git a/.gitignore b/.gitignore index ca7e335..ab25e85 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,6 @@ # File created using '.gitignore Generator' for Visual Studio Code: https://bit.ly/vscode-gig - -# Created by https://www.toptal.com/developers/gitignore/api/windows,visualstudiocode,visualstudio,rider,macos,linux,backup,dotenv -# Edit at https://www.toptal.com/developers/gitignore?templates=windows,visualstudiocode,visualstudio,rider,macos,linux,backup,dotenv +# Created by https://www.toptal.com/developers/gitignore/api/windows,visualstudiocode,visualstudio,rider,macos,linux,dotenv,backup,mdbook +# Edit at https://www.toptal.com/developers/gitignore?templates=windows,visualstudiocode,visualstudio,rider,macos,linux,dotenv,backup,mdbook ### Backup ### *.bak @@ -57,12 +56,43 @@ Network Trash Folder Temporary Items .apdisk +### macOS Patch ### +# iCloud generated files +*.icloud + +### MdBook ### +book + + ### Rider ### # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 # User-specific stuff -.idea/** +.idea/**/workspace.xml +.idea/**/tasks.xml +.idea/**/usage.statistics.xml +.idea/**/dictionaries +.idea/**/shelf + +# AWS User-specific +.idea/**/aws.xml + +# Generated files +.idea/**/contentModel.xml + +# Sensitive or high-churn files +.idea/**/dataSources/ +.idea/**/dataSources.ids +.idea/**/dataSources.local.xml +.idea/**/sqlDataSources.xml +.idea/**/dynamic.xml +.idea/**/uiDesigner.xml +.idea/**/dbnavigator.xml + +# Gradle +.idea/**/gradle.xml +.idea/**/libraries # Gradle and Maven with auto-import # When using Gradle or Maven with auto-import, you should exclude module files, @@ -98,6 +128,9 @@ atlassian-ide-plugin.xml # Cursive Clojure plugin .idea/replstate.xml +# SonarLint plugin +.idea/sonarlint/ + # Crashlytics plugin (for Android Studio and IntelliJ) com_crashlytics_export_strings.xml crashlytics.properties @@ -112,9 +145,17 @@ fabric.properties ### VisualStudioCode ### .vscode/* +!.vscode/settings.json !.vscode/tasks.json !.vscode/launch.json -*.code-workspace +!.vscode/extensions.json +!.vscode/*.code-snippets + +# Local History for Visual Studio Code +.history/ + +# Built Visual Studio Code Extensions +*.vsix ### VisualStudioCode Patch ### # Ignore all local history of files @@ -151,7 +192,7 @@ $RECYCLE.BIN/ ## Ignore Visual Studio temporary files, build results, and ## files generated by popular Visual Studio add-ons. ## -## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore +## Get latest from https://github.com/github/gitignore/blob/main/VisualStudio.gitignore # User-specific files *.rsuser @@ -173,6 +214,7 @@ mono_crash.* [Rr]eleases/ x64/ x86/ +[Ww][Ii][Nn]32/ [Aa][Rr][Mm]/ [Aa][Rr][Mm]64/ bld/ @@ -211,6 +253,9 @@ project.lock.json project.fragment.lock.json artifacts/ +# ASP.NET Scaffolding +ScaffoldingReadMe.txt + # StyleCop StyleCopReport.xml @@ -235,6 +280,7 @@ StyleCopReport.xml *.tmp_proj *_wpftmp.csproj *.log +*.tlog *.vspscc *.vssscc .builds @@ -287,7 +333,9 @@ _TeamCity* !.axoCover/settings.json # Coverlet is a free, cross platform Code Coverage Tool -coverage*[.json, .xml, .info] +coverage*.json +coverage*.xml +coverage*.info # Visual Studio code coverage results *.coverage @@ -435,6 +483,15 @@ node_modules/ # Visual Studio 6 auto-generated workspace file (contains which files were open etc.) *.vbw +# Visual Studio 6 auto-generated project file (contains which files were open etc.) +*.vbp + +# Visual Studio 6 workspace and project file (working project files containing files to include in project) +*.dsw +*.dsp + +# Visual Studio 6 technical files + # Visual Studio LightSwitch build output **/*.HTMLClient/GeneratedArtifacts **/*.DesktopClient/GeneratedArtifacts @@ -491,6 +548,9 @@ ASALocalRun/ # Local History for Visual Studio .localhistory/ +# Visual Studio History (VSHistory) files +.vshistory/ + # BeatPulse healthcheck temp database healthchecksdb @@ -500,7 +560,23 @@ MigrationBackup/ # Ionide (cross platform F# VS Code tools) working folder .ionide/ -# End of https://www.toptal.com/developers/gitignore/api/windows,visualstudiocode,visualstudio,rider,macos,linux,backup,dotenv +# Fody - auto-generated XML schema +FodyWeavers.xsd + +# VS Code files for those working on multiple tools +*.code-workspace + +# Local History for Visual Studio Code + +# Windows Installer files from build outputs + +# JetBrains Rider +*.sln.iml + +### VisualStudio Patch ### +# Additional files built by Visual Studio + +# End of https://www.toptal.com/developers/gitignore/api/windows,visualstudiocode,visualstudio,rider,macos,linux,dotenv,backup,mdbook # Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option) diff --git a/README.md b/README.md index 12e81c7..5d3c0da 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # TOMAS

- +
- +

@@ -18,9 +18,9 @@ TOMAS (**To**ny's **Ma**naged Operating **S**ystem) is a hobby operating system based on the [COSMOS](https://github.com/CosmosOS/Cosmos) framework that comes with a respective terminal emulator. -## Fictional version + ## Requirements diff --git a/docs/.vscode/settings.json b/docs/.vscode/settings.json new file mode 100644 index 0000000..5af1e3e --- /dev/null +++ b/docs/.vscode/settings.json @@ -0,0 +1,4 @@ +{ + "editor.tabCompletion": "on", + "diffEditor.codeLens": true +} \ No newline at end of file diff --git a/docs/.vscode/tasks.json b/docs/.vscode/tasks.json new file mode 100644 index 0000000..b0d5c60 --- /dev/null +++ b/docs/.vscode/tasks.json @@ -0,0 +1,25 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "build", + "type": "shell", + "command": "mdbook build", + "problemMatcher": [] + }, + { + "label": "clean", + "type": "shell", + "command": "mdbook clean", + "problemMatcher": [] + }, + { + "label": "serve", + "type": "shell", + "command": "mdbook serve", + "problemMatcher": [] + } + ] +} diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000..4e70a1f --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,17 @@ +[book] +authors = ["Tony Bark"] +language = "en" +multilingual = false +src = "src" +title = "TOMAS" + +[build] +create-missing = false + +[output.html] +no-section-label = true +git-repository-url = "https://github.com/tonytins/tomas" +additional-css = ["custom.css"] + +[output.html.fold] +enable = true \ No newline at end of file diff --git a/docs/custom.css b/docs/custom.css new file mode 100644 index 0000000..1c1a323 --- /dev/null +++ b/docs/custom.css @@ -0,0 +1,3 @@ +code { + white-space : pre-wrap !important; +} \ No newline at end of file diff --git a/docs/src/README.md b/docs/src/README.md new file mode 100644 index 0000000..82216bb --- /dev/null +++ b/docs/src/README.md @@ -0,0 +1,9 @@ +# Introduction + +

+ +

+ +TOMAS (**To**ny's **Ma**naged Operating **S**ystem) is a modular hobby operating system written in C# using the [COSMOS](https://github.com/CosmosOS/Cosmos) framework. It comes with a respective terminal emulator using for Core testing. + +Both the kernel and terminal emulator will eventually support programs and plugins, respectfully. With the former allowing for running of native .NET executables and the latter Lua plugins, while taking advantage of the existing [interface](./design/interfaces.md) architecture. diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 0000000..fd2f710 --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,14 @@ +# Summary + +- [Introduction](./README.md) +- [Changelog](./changelog.md) + +# Design + +- [Interfaces](./design/interfaces.md) +- [File System]() +- [Translations]() + +# Nethington + +- [Compliance](./nethington/compliance.md) \ No newline at end of file diff --git a/docs/src/changelog.md b/docs/src/changelog.md new file mode 100644 index 0000000..0e5eedc --- /dev/null +++ b/docs/src/changelog.md @@ -0,0 +1,23 @@ +# Changelog + +## 23.1 + +- With the help of ChatGPT, the ``IProgram`` interface has been rewritten to handle command line arguments. Being ChatGPT derived, it's still rough around the edges (not sure what to do with ``IArguments`` right now), but it's one hell of a jumping start! +- Speaking of, the [CST parser](https://github.com/tonytins/cstdotnet) has been rewritten to finally support arguments with the help of ChatGPT too. While I could have always looked at FreeSO's implantation for reference, that code is just awful. It will be ported back upstream ASAP! + +## 23.0 + +- Split versioning systems between kernal and terminal + - Calendar versioning, `YY.MINOR.MICRO`, for kernal + - Semantic versioning for terminal +- If the file system is activate, system activity will be logged +- Build number based on commit hash + +Due to the huge time skip and architectural changes, I've (retroactively) switched to calendar versioning with ``v0.1`` now known as ``v20.1`` as well. + +## 20.1 + +- Filesystem (based on the Cosmos Wiki [guide](https://csos-guide-to-cosmos.fandom.com/wiki/Getting_Started_-_Materials_and_Setting_Up)) +- Semantic versioning +- Replaced BasicApp with AboutApp +- Removd TerminalCancelEventArgs and everything related to it \ No newline at end of file diff --git a/docs/src/design/filesystem.md b/docs/src/design/filesystem.md new file mode 100644 index 0000000..0ee70e6 --- /dev/null +++ b/docs/src/design/filesystem.md @@ -0,0 +1,3 @@ +# File System + +Since 19.1, a virtual file system was introduced based on ``CosmosVFS`` and ``VFSManager``, respectfully. diff --git a/docs/src/design/interfaces.md b/docs/src/design/interfaces.md new file mode 100644 index 0000000..8c63eef --- /dev/null +++ b/docs/src/design/interfaces.md @@ -0,0 +1,29 @@ +# Interfaces + +Since 19.1, TOMAS uses a modular interface design for writing and executing programs. At the moment, the operating system doesn't yet support loading assemblies that would take advantage of this API, but it is being looked into. + +## Design + +``IProgram`` is used to create the actual program while ``IShell`` executes the respective program from a dictionary. While still early in development, the approach has allowed for easy migration from one major release of COSMOS to another with little to no modifications of the code itself. + +```csharp +public interface IProgram +{ + string Name { get; } + + string Description { get; } + + bool Entry(IShell shell, IEnumerable> arguments); +} +``` + +```csharp +public interface IShell +{ + string ReadLine { get; } + + Dictionary Programs { get; } + + IEnumerable>? ParseArguments(IProgram program, string[] arguments); +} +``` diff --git a/docs/src/design/translations.md b/docs/src/design/translations.md new file mode 100644 index 0000000..41ca7da --- /dev/null +++ b/docs/src/design/translations.md @@ -0,0 +1,3 @@ +# Translations + +Since 23.0, TOMAS uses a derivative of [CST.NET](https://github.com/tonytins/cstdotnet) for handling translations. Naturally, it follows the same [interface](./interfaces.md) paradigm as described in the last chapter with ``IUIText`` being renamed to ``ITranslations``, located in ``Tomas.Interface.Globalization``, but the two remain compatible. Changes made here will eventually make their way back upstream. diff --git a/docs/src/nethington/compliance.md b/docs/src/nethington/compliance.md new file mode 100644 index 0000000..1275a61 --- /dev/null +++ b/docs/src/nethington/compliance.md @@ -0,0 +1,7 @@ +# Compliance with Regulations in Nethington + +In order to comply with the Nethington[^1] government's [adoption of open-source software](https://nethington.tonybark.com/bills/drafts/hr2.html) for all government-owned computer systems, TOMAS will be used as government software. The operating system will meet the functional and technical requirements of the government and adhere to the principles of responsible and open source development. TOMAS will meet the requirements for strong track record of security and stability, and be in compliance with all applicable laws and regulations, including those outlined in [Article V](https://nethington.tonybark.com/constitution.html#article-v-cybersecurity) of the Constitution regarding cybersecurity and the use of long-term support or enterprise-grade open source software. The Nethington Cybersecurity Agency (NCA) will evaluate TOMAS and determine its suitability for use by the government. TOMAS will implement software to keep the identity of individuals working for the NCA confidential as further outlined in Article V of the Constitution. + +## Footnotes + +[^1]: [Nethington](https://nethington.tonybark.com) is another hobby project of mine in the form of micronation, \ No newline at end of file diff --git a/assets/logo.png b/docs/src/static/imgs/logo.png similarity index 100% rename from assets/logo.png rename to docs/src/static/imgs/logo.png diff --git a/assets/logo.svg b/docs/src/static/imgs/logo.svg similarity index 100% rename from assets/logo.svg rename to docs/src/static/imgs/logo.svg diff --git a/assets/screenshot.png b/docs/src/static/imgs/screenshot.png similarity index 100% rename from assets/screenshot.png rename to docs/src/static/imgs/screenshot.png diff --git a/assets/social-preview.png b/docs/src/static/imgs/social-preview.png similarity index 100% rename from assets/social-preview.png rename to docs/src/static/imgs/social-preview.png diff --git a/assets/social-preview.xcf b/docs/src/static/imgs/social-preview.xcf similarity index 100% rename from assets/social-preview.xcf rename to docs/src/static/imgs/social-preview.xcf