Skip to content

Commit

Permalink
Migrate Documentation to MkDocs (#902)
Browse files Browse the repository at this point in the history 
* WIP: Getting started on MkDocs for NMA

* Updated: The State of Documentation

* By the venerable quills of documentation, knowledge hath been inscribed like a beacon of wisdom in the annals of understanding! But heed this, the journey to elucidate and enlighten shall be vast and intricate, akin to navigating the labyrinthine depths of the most profound library.

* Updated: Localization & Translation Docs

* Added: Some Localization & Some SkyrimSE Info

* WIP: We are a step closer to make UI Guidelines Understandable in ELI5 fashion

* Improved: Accessibility and formatting of UI Coding Guidelines

* Reworked: UI Styling Guidelines for the New Docs

* Reworked: FileSystem Guidelines for New Docs

* Fixup Formatting in Remaining Files

* Leave stub in Readme.md

---------

Co-authored-by: Timothy Baldridge <[email protected]>
  • Loading branch information
@Sewer56 @halgari
Sewer56 and halgari authored Feb 1, 2024
1 parent b8da7e4 commit 39cbc93
Show file tree
Hide file tree
Showing 48 changed files with 2,421 additions and 1,027 deletions.
35 changes: 35 additions & 0 deletions .github/workflows/deploy-docs.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
name: Deploy MkDocs

# Controls when the action will run.
on:
# Triggers the workflow on push on the master branch
push:
branches: [ main ]

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
# This workflow contains a single job called "build"
build:
# The type of runner that the job will run on
runs-on: ubuntu-latest

# Steps represent a sequence of tasks that will be executed as part of the job
steps:

# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- name: Checkout Branch
uses: actions/checkout@v2
with:
submodules: recursive

# Deploy MkDocs
- name: Deploy MkDocs
# You may pin to the exact commit or the version.
# uses: mhausenblas/mkdocs-deploy-gh-pages@66340182cb2a1a63f8a3783e3e2146b7d151a0bb
uses: mhausenblas/mkdocs-deploy-gh-pages@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
REQUIREMENTS: ./docs/requirements.txt
3 changes: 3 additions & 0 deletions .gitmodules
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[submodule "docs/Nexus"]
path = docs/Nexus
url = https://github.com/Nexus-Mods/NexusMods.MkDocsMaterial.Themes.Next.git
1 change: 1 addition & 0 deletions NexusMods.App.sln
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = ".solutionItems", ".solution
README.md = README.md
Directory.Packages.props = Directory.Packages.props
.gitignore = .gitignore
mkdocs.yml = mkdocs.yml
EndProjectSection
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "NexusMods.Games.FOMOD", "src\Games\NexusMods.Games.FOMOD\NexusMods.Games.FOMOD.csproj", "{B43A31B2-1F08-4D8E-9C45-48015FBA983E}"
Expand Down
86 changes: 22 additions & 64 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,64 +1,22 @@
# Nexus Mods App

[![CI Tests](https://github.com/Nexus-Mods/NexusMods.App/actions/workflows/clean_environment_tests.yaml/badge.svg)](https://github.com/Nexus-Mods/NexusMods.App/actions/workflows/clean_environment_tests.yaml)
[![Discord](https://img.shields.io/discord/1134149061080002713?logo=discord&logoColor=white&color=7289da)](https://discord.gg/ReWTxb93jS)


This is the repository for the Nexus Mods App, a mod installer, creator and manager for all your popular games

## Mod with confidence

One of the biggest complaints of users over the years about mod managers is that they can't mod with confidence. Will a new mod wreck their
existing install? Will copying some files into their game folder require them to delete the entire game if they want to revert these changes? The
game updated, and the user updated their mods, now nothing works! Every step of the modding process is fraught with pitfalls and destructive changes.

The Nexus Mods App intends to solve these problems. In addition to being a great mod installer, manager and builder, this project aims to always
provide an "undo" feature for users. Not just on a metadata level (like most mod managers offer today) but on a per-file basis as well. So go ahead,
update that mod, if you don't like it, you can always go back to the game as it was before you made the update.

Further Reading : [Immutable Mod Lists](/docs/ImmutableModlists.md)

## Simple Data Model

Most Mod managers have serious drawbacks and edge cases in how they manage files, most of these systems (hard links, VFS systems) start with a goal
of keeping the game folder clean, but have the side effect of introducing concepts that are foreign to users. The average gamer isn't aware of concepts
such as function hooking (VFS) or hard links. In addition the [incidental complexity](https://dev.to/alexbunardzic/software-complexity-essential-accidental-and-incidental-3i4d)
of these systems often leak through the mod manager abstractions in unexpected ways.

For example:

* You have to run xEdit through MO2's app for it to see your mod list
* Your staging folders must be on the same drive as your game if your game doesn't support symlinks
* How do you know if your game supports symlinks?
* Links have strange side-effects when files are modified, depending if the file was direct modified or deleted-created-modified.

The Datamodel of the Nexus Mods App can be thought of as an extension of lessons learned from the development of Nexus Collections and Wabbajack.
Put simply, this app doesn't directly manipulate files while creating your modlist. Instead users manipulate the install instructions of the mod list
and then clicking "Apply" writes this mod list directly to the game folder, but in a way that allows users to revert these changes at any time. Since files are not staged or
linked in game folders, and no functions are hooked, the [cognitive overhead](https://techcrunch.com/2013/04/20/cognitive-overhead/) of the modding process is greatly reduced,
and users can focus on creating a perfect modding setup.

TL;DR - The Nexus Mods App aims to merge the mental simplicity of manual modding, with the hygiene of existing mod installers, and a promise of: "you can always go back to what last worked"

Further Reading: [Comparison of File Management Systems](/docs/ComparisonOfFileManagementSystems.md)

## FAQ

**Q:** What is this? A replacement for Vortex?

**A:** Eventually, yes. But not for quite some time, at the moment this software should be considered "pre-alpha". Do not ask for support for these tools until official announcements and a product launch is made. Feel free to direct any questions to halgari in the meantime.


**Q:** Why is this being done, why a new platform, design, etc.?

**A:** Vortex was designed primarily for development by a team of one person (Tannin), as at the time Nexus wasn't ready to take on the financial and leadership burden of a larger development team. However, times change and we're now in the position of being able to have a more well structured team and development schedule. As such we are increasing the size of our mod management team. On the technical side of things we're taking time to lay a solid CI foundation, setup a well rounded datamodel (using lessons we've learned over the years of developing Vortex), and build this project to be more of a company product and less of a community project.


**Q:** Company product? Is this going closed source?

**A:** Absolutely not, modding tools should be free, and the Nexus Mods App will always be open source (GPL3). But we also want to use this app as a way to get tools into the hands of modders and users. Instead of publishing only a download API, we want to give users a download CLI tool. Once file uploading is reworked on the site, this repo will contain the code and CLI tools required for authenticating with the Nexus and uploading files via a CLI (and eventually a UI). In short, this is us getting serious about supporting (and leading) the desktop side of modding, not just the file hosting side.


**Q:** I see tests run on Linux, Windows and OSX, are you targeting all those platforms?

**A:** Yes, the CLI runs on these platforms and we run our CI on each of these OSes. What games are supported on these platforms (e.g. do we support Skyrim through Wine on Linux?) is yet to be determined.
<div align="center">
<h1>The Nexus Mods App</h1>
<img src="docs/Nexus/Images/Nexus-Icon.png" width="150" align="center" />
<br/> <br/>
Mod With Confidence
<br/>
The <i>future</i> of modding with <i>Nexus</i>.
<br/><br/>
<a href="https://github.com/Nexus-Mods/NexusMods.App/actions/workflows/clean_environment_tests.yaml" target="_blank">
<img src="https://github.com/Nexus-Mods/NexusMods.App/actions/workflows/clean_environment_tests.yaml/badge.svg" alt="CI Tests">
</a>
<a href="https://discord.gg/ReWTxb93jS" target="_blank">
<img src="https://img.shields.io/discord/1134149061080002713?logo=discord&logoColor=white&color=7289da" alt="Discord">
</a>
</div>

Nexus Mods App is a mod installer, creator and manager for all your popular games.

Easy to use, runs on your standard Windows PC and Linux alike. Don't waste time troubleshooting, play your games,
fill those knees with arrows and most importantly, ***Have Fun***!

Learn more about the App on the Wiki [Insert Link Here After Merging PR]
43 changes: 0 additions & 43 deletions docs/AddingAGame.md
View file

This file was deleted.

20 changes: 20 additions & 0 deletions docs/FAQ.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
### FAQ

**Q:** What is this? A replacement for Vortex?

**A:** Eventually, yes. But not for quite some time, at the moment this software should be considered "pre-alpha". Do not ask for support for these tools until official announcements and a product launch is made. Feel free to direct any questions to halgari in the meantime.


**Q:** Why is this being done, why a new platform, design, etc.?

**A:** Vortex was designed primarily for development by a team of one person (Tannin), as at the time Nexus wasn't ready to take on the financial and leadership burden of a larger development team. However, times change and we're now in the position of being able to have a more well structured team and development schedule. As such we are increasing the size of our mod management team. On the technical side of things we're taking time to lay a solid CI foundation, setup a well rounded datamodel (using lessons we've learned over the years of developing Vortex), and build this project to be more of a company product and less of a community project.


**Q:** Company product? Is this going closed source?

**A:** Absolutely not, modding tools should be free, and the Nexus Mods App will always be open source (GPL3). But we also want to use this app as a way to get tools into the hands of modders and users. Instead of publishing only a download API, we want to give users a download CLI tool. Once file uploading is reworked on the site, this repo will contain the code and CLI tools required for authenticating with the Nexus and uploading files via a CLI (and eventually a UI). In short, this is us getting serious about supporting (and leading) the desktop side of modding, not just the file hosting side.


**Q:** I see tests run on Linux, Windows and OSX, are you targeting all those platforms?

**A:** Yes, the CLI runs on these platforms and we run our CI on each of these OSes. What games are supported on these platforms (e.g. do we support Skyrim through Wine on Linux?) is yet to be determined.
47 changes: 20 additions & 27 deletions docs/GettingStarted.md
View file
Original file line number Diff line number Diff line change
@@ -1,40 +1,33 @@
## Getting Started in Development
!!! info "Describes how to compile and run the Nexus App."

The Nexus App is programmed in C# with latest .NET Runtime. Setup should be easy.

The NexusMods.App is programed in C# and .NET 7. We have worked hard to make the startup process for the application as simple as possible.

## Prerequisites

### Prerequisites
- Download the Latest [.NET SDK](https://dotnet.microsoft.com/en-us/download/dotnet/7.0).
- Download an IDE, recommended options below:
- [Visual Studio](https://visualstudio.microsoft.com/downloads/)
- [JetBrains Rider](https://www.jetbrains.com/rider/)

To start with, you'll want to download the .NET 7 SDK (https://dotnet.microsoft.com/en-us/download/dotnet/7.0). You'll also need an IDE of some sort. Most of our developers prefer [JetBrains Rider](https://www.jetbrains.com/rider/), but [Visual Studio](https://visualstudio.microsoft.com/downloads/) is an alternative. While Visual Studio code may also work, these more advanced editors will provide superior feedback and tooling.
Our development team uses Rider, however Visual Studio is a great free offering on Windows.
Other code editors like [VSCode](https://code.visualstudio.com/) may work for you with [extensions](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit),
however may be a bit more complicated to use.

All other code and library dependencies are handled by NuGet and will be downloaded automatically when the application is built.
There are no other language or runtime dependencies.
That's all. Open the project (`.sln`), build, and you're done.

### Useful tools:
Visual Studio and JetBrains Rider both have avalonia extensions that allow previewing ui designs (.axaml files).
- Visual Studio: https://marketplace.visualstudio.com/items?itemName=AvaloniaTeam.AvaloniaVS
- Rider: https://plugins.jetbrains.com/plugin/14839-avaloniarider
## Tools for UI Development

Both extensions can be found directly from the IDE plugin/extension managers.
Using these extension is recommended for easier development.
Visual Studio and JetBrains Rider both have avalonia extensions that allow previewing ui designs (`.axaml` files).

There are also some Item Templates for Avalonia that can be very useful to have, available here:
- https://github.com/AvaloniaUI/avalonia-dotnet-templates
- [Visual Studio Extension](https://marketplace.visualstudio.com/items?itemName=AvaloniaTeam.AvaloniaVS)
- [Rider Extension](https://plugins.jetbrains.com/plugin/14839-avaloniarider)

### Code Overview
You can install via web or from inside the IDEs extension managers themselves.

The NexusMods.App makes heavy use of Microsoft Dependency Injection. During application startup, modules are added to a `IServiceCollection` tagged by one or more type names. In may places in the code, you can see many examples of this registration
There are also some [Item Templates](https://github.com/AvaloniaUI/avalonia-dotnet-templates) for Avalonia that can be very useful to have,
helping you make things like new 'Windows' and 'Controls' easier.

```csharp
services.AddSingleton<Foo>() // Register Foo as a provider of the Foo type
servcies.AddSingleton<IFoo, Foo>() // Register Foo as a provider of the IFoo interface
services.AddAllSingleton<IFoo, IFoo<long>, Foo>() // Register Foo as a provider of
```
## Code Guidelines

Once the application starts, a `IServiceProvider` is created which can be used to get instances of registered types. This provider also auto-resolves all the requirements of classes and injects instances into classes as it constructs them.
Coding against interfaces then allows for parts of the application to be stubbed out during testing, swapped out to meet future requirements, or to have different configurations of the application for different environments.

Because `IServiceProvider` can also resolve a collection of implementations, it's possible to get all the possible implementations of a iterfaces. For example `services.GetRequiredService<IEnumerable<IGame>>()`
will return all the registered implementations of `IGame`. This is used in many places in the application to allow for the application to be extended to support new games without needing to change the code in many places.
This behavior is also leveraged to allow libraries to hook aspects of the application without having to register event callbacks. Instead libraries register themselves in the DI system and the framework calls them as needed.
Have a look inside [Development Guidelines](./development-guidelines/DependencyInjection.md) 😉.
Loading

0 comments on commit 39cbc93

Please sign in to comment.