Merge pull request #2907 from CosmosOS/zarlo/docs/0

working on docs to make it a bit more useable
CosmosOS · Jan 22, 2024 · f7fd569 · f7fd569
2 parents 4cde93d + aaa42b0
commit f7fd569
Show file tree

Hide file tree

Showing 7 changed files with 128 additions and 37 deletions.
diff --git a/Docs/articles/Installation/DevKit.md b/Docs/articles/Installation/DevKit.md
@@ -1,30 +1,59 @@
 # Dev Kit Installation 
 
-###  Prerequisites for Windows
+## Windows
+
+###  Prerequisites
 
 * (Free) source code of Development Kit from [Cosmos on GitHub](https://github.com/CosmosOS/Cosmos)
    * You must clone the repository using Git. For a detailed walkthrough, [see here](https://help.github.com/articles/fork-a-repo/).
 * (Free) [Visual Studio 2022 Community](https://visualstudio.microsoft.com/vs/)  
 * (Free) [InnoSetup](http://www.jrsoftware.org/isdl.php#qsp)
    * This is required to build the setup kit which is used to build and install the Visual Studio integration libaries for Cosmos.
-    * During install it will ask you about optional components to install. Be sure you check "Install Inno Setup Preprocessor".
+   * During install it will ask you about optional components to install. Be sure you check "Install Inno Setup Preprocessor".
+
+###  Installation
+
+* Look in the downloaded sources and run **install-VS2022.bat** with admin privileges (UAC will ask for permission), needed for install in system directories.
+* When the installation is complete, Visual Studio will automatically open and you may begin programming with your new, modified copy of Cosmos.
+
 
-###  Prerequisites for Linux
+## Linux
+
+###  Prerequisites
 
 * .NET SDK (6+): [Download .NET SDK](https://learn.microsoft.com/en-us/dotnet/core/install/linux)
 * Make (`apt install make`)
 * Yasm (`apt install yasm`)
 * Xorriso (`apt install xorriso`)
 * QEMU or any other virtual machine. See [Running](https://cosmosos.github.io/articles/Installation/Running.html) for more information.
 
-###  Installation on Windows
 
-* Look in the downloaded sources and run **install-VS2022.bat** with admin privileges (UAC will ask for permission), needed for install in system directories.
-* When the installation is complete, Visual Studio will automatically open and you may begin programming with your new, modified copy of Cosmos.
-
-###  Installation on Linux
+###  Installation
 Run `make` to build Cosmos. Cosmos will clone all the required repos, build itself, and install it and it's nuget packages to the system automatically.
 
+## notes / FAQ
+
+### custom cosmos repos
+
+if you are using custom cosmos repos you will need to clone them all manually as the installer script will pull from https://github.com/CosmosOS/
+
+A tree diagram of the source should look like the following:   
+
+<img src="https://raw.githubusercontent.com/CosmosOS/Cosmos/master/Docs/images/Dir.png" width="200">
+
+
+### get stuck pulling the git repos
+
+check if git is installed and in your path as we use git to pull the repos
+
+### i just updated and my project is sill using the old version
+
+you may need to clear you nuget cache try ``dotnet clean`` to clear the project level cache
+
+### the project templates are not showing in visual studio
+
+if you have more then 1 version of visual studio installed this can bug this follow "dotnet Project Templates" should fix it
+
 ### dotnet Project Templates
 If you are using linux or prefer not using Visual Studio for your projects, you can install the dotnet project template using `dotnet new --install ./source/templates/csharp/` assuming you are currently in the Cosmos base directory.
 After installing the template use `dotnet new cosmosCSKernel -n {name}` to create a new Cosmos Kernel project. 

diff --git a/Docs/articles/Installation/UserKit.md b/Docs/articles/Installation/UserKit.md
@@ -0,0 +1,27 @@
+# Installation
+
+for DevKit / linux see [DevKit](DevKit.md)
+
+### Prerequisites
+
+
+*   **Visual Studio 2022** - [Download](https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx)
+*   **Visual Studio 2022 Workload: .NET Desktop** - .NET Desktop development
+*   **.NET 6.0** - [Download](https://www.microsoft.com/en-us/download/details.aspx?id=53321)
+*   **VMware Player or Workstation** VMware Player is free, so that is recommended instead - [Download](https://www.vmware.com/uk/products/workstation-player/workstation-player-evaluation.html)
+*   **Microsoft Visual C++ 2010 Redistributable** - [Download](https://www.microsoft.com/en-us/download/details.aspx?id=26999)
+
+### Installing Cosmos
+
+First, you need to choose between the User Kit and the Dev Kit. It is recommended that new users start with the User Kit but only move later to the Dev Kit if you need the latest features and want to contribute back to the main project. 
+The Dev Kit is the live source against which the Cosmos Team develops directly. The Dev Kit has the latest and greatest features, but at various times has known issues, and sometimes may not even build. Thus to use the Dev Kit be sure to join our support channels and inquire about the current status before using the Dev Kit or updating it. 
+
+The User Kit is a snapshot stable version of Cosmos including a premade installer. The UserKit however is often quite a bit out of date compared to the DevKit and is only occasionally updated. The User Kit is a great easy way to get familiar with Cosmos, but active developers should transition to the Dev Kit after becoming very familiar with the UserKit, and expect some bugs here and there.
+
+### User Kit
+
+1.  Download [the latest release of Cosmos](http://github.com/CosmosOS/Cosmos/releases/latest) (download the **exe** file)
+2.  Wait for the download to complete then run the installer. Allow it to run as admin. Make sure **VS2022 is NOT running** when you do this.
+3.  Click "Next" then "Install"
+4.  Wait for the install to progress. **Tip:** At the end the installer may look like it has stalled, but it is still doing something in the background. WAIT for the "Finish" button to become available.
+5.  Cosmos should now be installed. Follow other tutorials to find out how to create your first OS.
diff --git a/Docs/articles/toc.md b/Docs/articles/toc.md
@@ -8,6 +8,7 @@
 ## [Debug Commands](Debugger/DebugCommands.md)
 
 # Installation
+## [User Kit](Installation/UserKit.md)
 ## [Dev Kit](Installation/DevKit.md)
 ## [Running](Installation/Running.md)
 

diff --git a/Docs/docfx.json b/Docs/docfx.json
@@ -14,6 +14,42 @@
                 }
             ],
             "dest": "obj/api"
+        },
+        {
+            "src": [
+                {
+                    "files": [
+                        "source/Cosmos.Core/Cosmos.Core.csproj",
+                        "source/Cosmos.Core_Asm/Cosmos.Core_Asm.csproj",
+                        "source/Cosmos.HAL2/Cosmos.HAL2.csproj",
+                        "source/Cosmos.System2/Cosmos.System2.csproj",
+                        "source/Cosmos.Debug.Kernel/Cosmos.Debug.Kernel.csproj",
+                    ],
+                    "exclude": [
+                        "**/bin/**",
+                        "**/obj/**"
+                    ],
+                    "src": "../"
+                }
+            ],
+            "dest": "obj/api/cosmos"
+        },
+        {
+            "src": [
+                {
+                    "files": [
+                        "source/Cosmos.Core_Plugs/Cosmos.Core_Plugs.csproj",
+                        "source/Cosmos.HAL2/Cosmos.HAL2.csproj",
+                        "source/Cosmos.System2_Plugs/Cosmos.System2_Plugs.csproj"
+                    ],
+                    "exclude": [
+                        "**/bin/**",
+                        "**/obj/**"
+                    ],
+                    "src": "../"
+                }
+            ],
+            "dest": "obj/api/plugs"
         }
     ],
     "build": {
@@ -25,6 +61,20 @@
                 "src": "obj/api",
                 "dest": "api"
             },
+            {
+                "files": [
+                    "**/*.yml"
+                ],
+                "src": "obj/api/cosmos",
+                "dest": "api/cosmos"
+            },
+            {
+                "files": [
+                    "**/*.yml"
+                ],
+                "src": "obj/api/plugs",
+                "dest": "api/plugs"
+            },
             {
                 "files": [
                     "**/*.md",

diff --git a/Docs/index.md b/Docs/index.md
@@ -1,8 +1,8 @@
 # Welcome to the Official Cosmos Documentation</h1>
 
-If you're new to Cosmos, welcome! Before you get stuck in the API documentation, we highly recommend you visit the website linked at the bottom.  
+If you're new to Cosmos, welcome! Before you get stuck in the API documentation, we highly recommend you visit the website linked below.  
 
-The Articles section of this website includes some articles which have been written many years ago for websites such as www.codeproject.com and are kept for archival purposes. These discuss elements such as the Cosmos Virtual File System. We prefer newcomers who want to develop their own operating systems to read the API documentation while we update these articles to comply with the current Cosmos project. 
+The Articles section of this website includes some articles which have been written over years ago for websites such as www.codeproject.com and are mostly kept for archival purposes. These discuss elements such as the Cosmos Virtual File System. We prefer newcomers who want to develop their own operating systems to read the API documentation while we update these articles to comply with the current Cosmos project. 
 
 For projects using the VFS directly, we recommend you use System.IO methods where possible. This is because these were written before much progress was made making .NET assemblies usable
 
@@ -17,4 +17,6 @@ If you need a translation for this documentation, click [here](https://cosmosos-
 You can find the latest and previous build statuses on [AppVeyor](https://ci.appveyor.com/project/CosmosOS/cosmos)  
 
 [![Build status](https://ci.appveyor.com/api/projects/status/kust7g5dlnykhkaf/branch/master?svg=true)](https://ci.appveyor.com/project/CosmosOS/cosmos/branch/master)  
-[![Join the chat at (https://discord.com/invite/kwtBwv6jhD](https://img.shields.io/discord/833970409337913344)](https://discord.com/invite/kwtBwv6jhD)  
+[![Join the chat at (https://discord.com/invite/kwtBwv6jhD](https://img.shields.io/discord/833970409337913344)](https://discord.com/invite/kwtBwv6jhD)
+
+xref link [https://cosmosos.github.io/xrefmap.yml](https://cosmosos.github.io/xrefmap.yml)
diff --git a/Docs/install.md b/Docs/install.md
@@ -1,28 +1,4 @@
-# Installation
 
-### Prerequisites
-
-
-*   **Visual Studio 2022** - [Download](https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx)
-*   **Visual Studio 2022 Workload: .NET Desktop** - .NET Desktop development
-*   **.NET 6.0** - [Download](https://www.microsoft.com/en-us/download/details.aspx?id=53321)
-*   **VMware Player or Workstation** VMware Player is free, so that is recommended instead - [Download](https://www.vmware.com/uk/products/workstation-player/workstation-player-evaluation.html)
-*   **Microsoft Visual C++ 2010 Redistributable** - [Download](https://www.microsoft.com/en-us/download/details.aspx?id=26999)
-
-### Installing Cosmos
-
-First, you need to choose between the User Kit and the Dev Kit. It is recommended that new users start with the User Kit but only move later to the Dev Kit if you need the latest features and want to contribute back to the main project. 
-The Dev Kit is the live source against which the Cosmos Team develops directly. The Dev Kit has the latest and greatest features, but at various times has known issues, and sometimes may not even build. Thus to use the Dev Kit be sure to join our support channels and inquire about the current status before using the Dev Kit or updating it. 
-
-The User Kit is a snapshot stable version of Cosmos including a premade installer. The UserKit however is often quite a bit out of date compared to the DevKit and is only occasionally updated. The User Kit is a great easy way to get familiar with Cosmos, but active developers should transition to the Dev Kit after becoming very familiar with the UserKit, and expect some bugs here and there.
-
-### User Kit
-
-1.  Download [the latest release of Cosmos](http://github.com/CosmosOS/Cosmos/releases/latest) (download the **exe** file)
-2.  Wait for the download to complete then run the installer. Allow it to run as admin. Make sure **VS2022 is NOT running** when you do this.
-3.  Click "Next" then "Install"
-4.  Wait for the install to progress. **Tip:** At the end the installer may look like it has stalled, but it is still doing something in the background. WAIT for the "Finish" button to become available.
-5.  Cosmos should now be installed. Follow other tutorials to find out how to create your first OS.
 
 ### Dev Kit
 

diff --git a/Docs/toc.yml b/Docs/toc.yml
@@ -1,11 +1,17 @@
 - name: Home
   href: index.md
 - name: Install
-  href: install.md
+  href: articles/Installation/UserKit.md
 - name: Cosmos Website
   href: https://gocosmos.org
 - name: Articles
   href: articles/
   homepage: articles/GettingStarted.md
 - name: API Documentation
-  href: obj/api/
+  items:
+  - name: Cosmos
+    href: obj/api/cosmos
+  - name: X#
+    href: obj/api/xsharp
+  - name: IL2CPU
+    href: obj/api/il2cpu