KSP2 API DocFX Project | KSP2 Redux | Page 1

main swift Jun 1, 2023, 10:16 PM

#

This project aims to create an extensible online KSP2 API documentation site based on a stripped version of the KSP2 Assembly-CSharp.dll. The site contents are primarily two things. First, a stripped collection of C# files based on the stripped DLL, and secondly a DocFX generated API documentation site. The site will be served via GitHub Pages, and will permit extension via addition/modification of /// comments to the stripped C# files and via addition/modification of various article files (*.md).

As the DLL is first stripped of all internal code (all methods have their content replace with a return null;), there is no distribution of the games internal code and only documentation of the API as an interface with the added value of unofficial comments being incorporated to aid in documentation.

Step 1: The first step in this process is to strip all internal code from the Assembly-CSharp.dll. This can be accomplished in a number of ways, and we may wish to experiment with various ways to see which produces the best and most faithful rendering of the stripped DLL. In the initial approach this has been done using the BepInEx Publicizer, which can be installed and used like this:

dotnet tool install -g BepInEx.AssemblyPublicizer.Cli
assembly-publicizer ./Assembly-CSharp.dll --strip-only

The first line installs assembly-publicizer, and the second calls it to process Assembly-CSharp.dll with the command option --strip-only, which strips without publicizing.

See https://github.com/BepInEx/BepInEx.AssemblyPublicizer for more information on this tool.

GitHub

GitHub - BepInEx/BepInEx.AssemblyPublicizer

Contribute to BepInEx/BepInEx.AssemblyPublicizer development by creating an account on GitHub.

#

Step 2: Using the stripped version of the Assembly-CSharp.dll generated in Step 1 it's possible to create a C# project from that DLL. This is the step that produces the initial set of *.cs files to which we may manually add /// comments. There are several ways to do this, one being to load the stripped DLL into JetBrains dotPeek and use that tool to create a new Visual Studio project. As the input is a stripped DLL, the output does not contain any actual internal game code, but does capture namespaces, data, method interfaces, etc. Everything we need for the API documentation and nothing we're forbidden from sharing.

**Step 3: ** Using the stripped project generated in Step 2 it's possible to produce an Assembly-CSharp.xml file that is useful both for intellisence documentation for modding, and as an input to DocFX to supply the unofficial comments to go with the stripped DLL. This can be done using a variety of methods, one being GenDoc, which is a Roslyn API tool that can open a .sln file you point it to, and for each project that's in it, it goes through all the types and members and generates their XML documentation into a file per project.

GenDoc is called from the command line and take two arguments, the path to the .sln file and the output folder in which to deposit the resulting XML files. In this case there will be just one XML file, Assembly-CSharp.xml, and we want it to be located in the same folder along with the stripped version of Assembly-CSharp.dll

Step 4: Using the stripped DLL from Step 1 and the resulting XMl from Step 3, it's possible to generate useful API documentation using DocFX. This process requires 4 sub steps. 1. Install DocFx, 2. Build a docfx_project, 3. Edit the docfx.json file, and 4. Generate the DocFX site files. The first two steps are as follows

#

dotnet tool update -g docfx
docfx init --quiet```

#

This will create a docfx_project folder with a number of files in it, one of which will be docfx.json. Defore building the DocFX site files you need to edit that. Here's a copy of the version I've used which has worked.

{
  "metadata": [
    {
      "src": [
        {
          "files": ["Assembly-CSharp.dll",
                    "Assembly-CSharp.xml"],
          "src": "../DLL"
        }
      ],
      "dest": "api",
      "includePrivateMembers": false,
      "disableGitFeatures": false,
      "disableDefaultFilter": false,
      "noRestore": false,
      "namespaceLayout": "flattened",
      "memberLayout": "samePage",
      "allowCompilationErrors": false
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "output": "_site",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
      "default",
      "modern"
    ],
    "postProcessors": [],
    "keepFileLink": false,
    "disableGitFeatures": false
  }
}```

#

The important things to know are the (a) docfx is looking for relative paths, so with the "src" parameter set to "../DLL" that means it will look for the "files" in a folder named DLL that is located beside the "docfx_project" folder. Place the stripped DLL and resulting XML there, and then you're ready to generate the site files using this command.

docfx docfx_project/docfx.json --serve```
Note that when DocFX processes the stripped DLL it will report that there are many missing references. These don't matter and won't interfere with the process, so you can ignore those warnings.
The `--serve` command line argument will cause DocFX to serve up the resulting documentation site on your local machine at `http://localhost:8080`. This is useful for testing to make sure things are working OK and what you got from DocFX was good, but obviously this will not get the site served to the masses!

#

Step 5: At this point all we really have is a static site, and the next step is to publish this on GitHub Pages. The DocFX website has a guide for doing this, which links to GitHub's own documentation for setting up a GitHub Pages site, which is where I am now with this. You can find my test site here: https://schlosrat.github.io/index.html
The GitHub repo that's serving this site has two branches: main and gh-pages. I believe the gh-pages branch is where the actual site is served from, and there is a GitHub action that will take the content on the main branch and use this to build the site linked above. I'm a little fuzzy on the details here as I'm completely new to GitHub pages and GitHub Actions. In fact, I've not been able to get the GitHub action example from the DocFX site to work. Here it is:

jobs:
  publish-docs:
    runs-on: ubuntu-latest
    steps:
    - name: Chekout
      uses: actions/checkout@v3
    - name: Dotnet Setup
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 7.x

    - run: dotnet tool update -g docfx
    - run: docfx docfx_project/docfx.json

    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/_site```

#

What I have gotten to work, though not ideally, is the standard GitHub action code for a static site

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

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

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # Upload entire repository
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2```

#

The ultimate idea with this part is to have a GitHub action that will trigger when the main repo is updated so that it kicks off an automatic docfx job and re-publishes the page. For now, I'm doing that part manually on my desktop machine and using GitHub desktop to push the results back up where the stock GitHub static page action publishes it.

#

Step 6: The final step is to use the GitHub repo to enable extension of the documentation so that anyone in the modding community who wishes to contribute can and we'll all have a more useful set of documentation. For this, we need two things.
First, anyone wishing to contribute can (even now) fork the repo and make contributions https://github.com/schlosrat/schlosrat.github.io

GitHub

GitHub - schlosrat/schlosrat.github.io: KSP2 Unofficial API

KSP2 Unofficial API. Contribute to schlosrat/schlosrat.github.io development by creating an account on GitHub.

#

The main branch of the repo has two areas that you can easily contribute to. The first is the src_stripped folder. This holds the vs project for the stripped source that GenDocs uses to make the XML file. Just open it up in vs (or the IDE of your choice compatible with .csproj and .sln), and then add /// comments right before any stripped code method or object you would like to contribute documentation for.

#

The second way to contribute is to add or modify the .md files in the articles folder in the repo. These can be used to capture any API-relevant modding guidannce you like. Either way, make your changes and them give me a PR and I'll be able to incorporate them.

main swift Jun 2, 2023, 12:41 AM

#

The GitHub repo is organized with the following structure:
.github/workflows - contains the GitHub workflow actions (yml) that run when the repo is modified
DLL_stripped - contains the stripped Assembly-CSharp.dll and corresponding Assembly-CSharp.xml
api - contains the DocFX generated API files (html)
atricles - contains the DocFX generated article files (html & json)
docfx_project - contains the docfx.json, toc.yml, and article *.md files
public - contains DoxFX template files used when generating html files
src_stripped - contains the .csproj, .sln, and .cs files read by GenDoc to make the Assembly-SCharp.xml file
GenDoc.bat - a batch file for calling GenDoc to make the Assembly-CSharp.xml file
favicon.ico - a DocFX output file
index.html - A DocFX output file for the main page of the API documentation site
logo.png - the KSP2 Modding Discord logo
log0.svg - the default DocFX logo
manifest.json - a DocFX output file
search-stopwords.json - a DocFX output file
toc.html - a DocFX output file for the main page Table of Contents
toc.json - a DocFX output file
**xrefmap.yml **- a DocFX output file

main swift Jun 2, 2023, 12:56 AM

#

Of these, you should only ever need to modify either the .cs files in src_stripped (to add/modify unofficial documentation comments), or the .md files in docfx_project and it's subfolders (to add/modify the article pages (html) that DocFX generates). The files in DLL_stripped are inputs to DocFX, and the files in src_stripped are inputs to GenDoc. The files in api and articles are all outputs from DocFX.

#

@mossy harbor can you please check what I've written up here and make sure I'm on track?

mossy harbor Jun 2, 2023, 1:03 AM

#

yeah, that all sounds great

main swift Jun 2, 2023, 1:05 AM

#

Cool. I feel like I'm close at this point to having it really ready, but with two issues. For some reason the suggested GitHub action DocFX has isn't working for me, so I can only do the DocFX build locally and then push the results up. And then secondly I'm not sure how to make a GitHub action to get GenDoc to run. This mainly comes down to my lack of experience with GitHub Pages and GitHub Actions I think.

main swift Jun 2, 2023, 3:23 PM

#

API docs page updated: https://schlosrat.github.io/index.html
See guide on how to add content here: https://schlosrat.github.io/articles/intro.html

#

Still following a fairly manual process for the updates, but it's closing in on an automated process.

#

See the GitHub Actions here on the site: https://github.com/schlosrat/schlosrat.github.io/actions

GitHub

Actions · schlosrat/schlosrat.github.io

KSP2 Unofficial API. Contribute to schlosrat/schlosrat.github.io development by creating an account on GitHub.

#

Deploy Static Content to Pages works, but the Generate DocFx Content is giving me a weird Git permission error after it seems to run DocFX successfully, and the Generate XML Documentation is just not working at all yet - probably because I don't really understand how to make a GH Action do what I need it to with a run-on: windows-latest.

#

@mossy harbor , is there a linux version of GenDoc that I could get and try to run-on: ubuntu-latest?

mossy harbor Jun 2, 2023, 3:26 PM

#

you have the source code

#

so you can just build it

main swift Jun 2, 2023, 3:27 PM

#

I do. But I don't have a linux machine...

mossy harbor Jun 2, 2023, 3:27 PM

#

you can just build it inside the VM

#

/ action

main swift Jun 2, 2023, 3:27 PM

#

So, build it each time I need it? That may work

mossy harbor Jun 2, 2023, 3:28 PM

#

yeah, I mean the build process shouldn't take more than like a second

#

when you include nuget restore

main swift Jun 2, 2023, 3:28 PM

#

That whoosing sound you just heard was stuff going over my head...

#

I've updated the static.yml file to only deploy if either there's a push to the main branch that impacts either the api or articles folders, or if the action is manually triggered. This appears to be working. In fact it's the one action I've got that seems to work.

# Simple workflow for deploying static content to GitHub Pages
name: Deploy Static Content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]
    paths: ["api", "articles"]

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

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # Upload entire repository
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2```

#

I've used what I've learned playing with static.yml to try to update the action for building the DocFx content. This should now run only if there's a push to the main branch that impacts either the docfx_project, public, or DLL_stripped folders. This runs, but exits with an error after several minutes of DocFx apparently working.

# Simple workflow for deploying static content to GitHub Pages
name: Generate DocFx Content

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]
    paths: ["docfx_project", "public", "DLL_stripped"]
    
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
  
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
# permissions:
#   contents: read
#   pages: write
#   id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  publish-docs:
    runs-on: ubuntu-latest
    steps:
    - name: Chekout
      uses: actions/checkout@v3
    - name: Dotnet Setup
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 7.x

    - run: dotnet tool update -g docfx
    - run: docfx docfx_project/docfx.json

    #- name: Deploy
    #  uses: peaceiris/actions-gh-pages@v3
    #  with:
    #    github_token: ${{ secrets.GITHUB_TOKEN }}
    #    publish_dir: _site
    
    #- name: Upload artifact
    #  uses: actions/upload-pages-artifact@v1
    #  with:
    #    # Upload entire repository
    #    path: '.'
    #- name: Deploy to GitHub Pages
    #  id: deployment
    #  uses: actions/deploy-pages@v2```

#

The error I was getting was Action failed with "The process '/usr/bin/git' failed with exit code 128". The last time I ran it (1 hour ago) it spent a good 6:19 running before giving me this. I had thought it was giving me this error based on the deploy part, so I'd commented that out. Now I suspect it might be something in the docfx.json since I'm still getting this error, but whatever it is, it occurs late in the process.

#

I've added a GenDoc.yml file to try to make the Assembly-CSharp.xml file by following the static.yml file as a template. This is what I have, and so far it doesn't work. My hunch is I'm trying to run things under windows-latest in a way that makes it unhappy.

# Simple workflow for generating XML documentation
name: Generate XML Documentation

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]
    paths: ["src_stripped"]

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

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
# permissions:
#   contents: read
#   pages: write
#   id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
# concurrency:
#   group: "pages"
#   cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: windows-latest
    steps:
      - name: Generate XML Documentation
        run: Import-Module GenDoc
        run: GenDoc\GenDoc.exe src_stripped\Assembly-CSharp-Stripped.sln DLL_stripped
        run: call GenDoc.bat```

#

Hmmm... I may have fixed the GenDoc.yml...

#

#

It seems to have run and consequently put a new Assembly-CSharp.xml into DLL-Stripped, which has now caused the DocFX action to kick off.

#

Yep!

#

#

No, I take that back. I kicked off the Generate DocFx Content action, which did run! So, success, but a different flavor.

main swift Jun 2, 2023, 5:49 PM

#

Looking at this for an alternative way to build the DocFx files
https://github.com/NUnit/docfx-action

GitHub

GitHub - nunit/docfx-action

Contribute to nunit/docfx-action development by creating an account on GitHub.

main swift Jun 2, 2023, 6:25 PM

#

This seems to work for running GenDoc, except that it also doesn't seem to work

#

# Simple workflow for generating XML documentation
name: Generate XML Documentation

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]
    paths: ["src_stripped"]

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

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  # Single deploy job since we're just deploying
  build:
    runs-on: windows-latest
    steps:
      - name: Checkout
        uses: actions/checkout@master
      - name: Check Assembly-CSharp.xml
        run: dir DLL_stripped
        shell: cmd
      - name: Generate XML Documentation Directly
        run: GenDoc\GenDoc.exe src_stripped\Assembly-CSharp-Stripped.sln DLL_stripped
        shell: cmd
      - name: Check Assembly-CSharp.xml
        run: dir DLL_stripped
        shell: cmd
      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: Assembly-CSharp.xml
          path: DLL_stripped/Assembly-CSharp.xml

#

On the plus side, no errors, and it spends a reasonable 37 seconds running GenDoc. The trouble is that I don't see a difference between the dir of the DLL_stripped folder between the before and after. I'll try it again after putting in some more code comments, but it sort of seems like it works, but it doesn't.

#

The thing is, each GitHub action takes place in a brand new VM. The VM is completely empty at first, too - which is why the actions/checkout@master is needed. Without that there's none of the GitHub repos files present, and after that it's all present. Figuring that part out was a big enabler for getting the rest to run. The actions/upload-artifact@v3 at the end is what I think will push the resulting new Assembly-CSharp.xml back to the repo, and it does claim that it works, but as I said I can't tell any difference in the before and after on that file. I'm not expecting a size difference, but a new modification date/time would be nice to see.

mossy harbor Jun 2, 2023, 6:32 PM

#

it uploads the artifact for you to use it in another action

#

not into the repository

main swift Jun 2, 2023, 6:32 PM

#

Oh, so I'm calling the wrong action at the end then?

#

What I believe I want is to have this action result in a new copy of the xm file in the repo, so that the DocFX action can detect that and run

mossy harbor Jun 2, 2023, 6:34 PM

#

you can see the artifact here for example

#

https://github.com/schlosrat/schlosrat.github.io/actions/runs/5158536975

GitHub

Generate XML Documentation · schlosrat/schlosrat.github.io@3807c67

KSP2 Unofficial API. Contribute to schlosrat/schlosrat.github.io development by creating an account on GitHub.

main swift Jun 2, 2023, 6:35 PM

#

Even so, there are two dir command in there, before and after the GenDoc command, and there's no apparent diff in the file they see

#

I see that artifact now. Thanks for pointing that out

mossy harbor Jun 2, 2023, 6:35 PM

#

main swift What I believe I want is to have this action result in a new copy of the xm file...

not really, you don't want the repo to be changed by the action

#

you correctly upload the artifact

#

and then you need to fetch the artifact from the following action

#

https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts there are details about this in the docs

GitHub Docs

Storing workflow data as artifacts - GitHub Docs

main swift Jun 2, 2023, 6:36 PM

#

Not saying that wouldn't work, but what about the use case that someone would like a copy of the xml file to use in their mod development?

mossy harbor Jun 2, 2023, 6:37 PM

#

then you make a release with it in the action or something like that

#

files generated at build time shouldn't really enter the repository

#

ideally you'd make a nuget package with the XML and the stripped DLL and publish it to Nuget

main swift Jun 2, 2023, 6:38 PM

#

Ordinarily I'd agree, those are intermediate files and they get trashed (or can be trashed), but this is something a modder want to get from the repo and tuck into the folder with the dll for intellisence, no?

mossy harbor Jun 2, 2023, 6:38 PM

#

no, they shouldn't use a DLL at all (ideally)

main swift Jun 2, 2023, 6:38 PM

#

Oh, wait, I see where you're going now with nuget.

#

Not saying they'd use the DLL. I thought the idea was they could pull down a copy of the xml and stuff it into the same folder with the DLL they need anyway

mossy harbor Jun 2, 2023, 6:40 PM

#

but they don't

#

since the DLL is now inside the KerbalSpaceProgram2.GameLibs package

#

which should be prefered over a direct Assembly-CSharp.dll reference

main swift Jun 2, 2023, 6:40 PM

#

You're talking about the new template now. I'm still on the old one

mossy harbor Jun 2, 2023, 6:40 PM

#

and even if you didn't want to bother with making a nuget package, why would it be an issue if the modders downloaded the .xml file from a release instead of the repository?

#

by release I mean this

#

except it would contain the XML file

main swift Jun 2, 2023, 6:41 PM

#

No issue. Just hadn't really thought of it

#

In fact pulling it form a release is probably better

mossy harbor Jun 2, 2023, 6:41 PM

#

that's really the place for build products such as the XML file

main swift Jun 2, 2023, 6:44 PM

#

OK, so we're about 95-99% of the way to getting GenDoc to work automatically. I say that because I haven't tested this apparently working action to see if it will trigger correcting when a file in src_stripped is changed - I've just triggered it manually so far. If it runs automatically in the right conditions, then this piece is basically done and we can move on to releasing the xml, putting it in a NuGet, and making sure the DocFx build gets it.

#

That last is also partly why I thought I needed it back in the repo since DocFx is expecting it to be in the DLL_stripped folder along side the stripped DLL

#

I'm not clear on how we fix that to use the new artifact.

mossy harbor Jun 2, 2023, 6:45 PM

#

the issue is probably that this should all be a single action

#

with several separate jobs

#

instead of separate actions

#

I don't think you can share artifacts easily across different actions

main swift Jun 2, 2023, 6:46 PM

#

Ahh, OK. I can continue to test them separately, but they would need to be joined into a single action to really work.

#

In that case then I think we may be getting a lot closer.

main swift Jun 2, 2023, 9:33 PM

#

OK, I've got an action that seems to combine the DocFX generation and the deploy to GitHub Pages

# Simple workflow for generating DocFx Content and publish to GitHub Pages
name: Generate and Publish DocFx Content

on:
  # Runs on pushes targeting the default branch and impacting either the docfx_project, public, or DLL_stripped folders
  push:
    branches: ["main"]
    paths: ["docfx_project", "public", "DLL_stripped"]
    
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
  
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  publish-docs:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Chekout
        uses: actions/checkout@v3
      - name: Dotnet Setup
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: 7.x

      - run: dotnet tool update -g docfx
      - run: docfx docfx_project/docfx.json
      #- name: Deploy
      #  uses: peaceiris/actions-gh-pages@v3
      #  with:
      #    github_token: ${{ secrets.GITHUB_TOKEN }}
      #    publish_dir: _site
    
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # Upload entire repository
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2```

#

I'm fuzzy on how I'd get the artifact from the other job as it's running on windows-latest and so has a different environment. Even if I combined that with this to make one mega job, the windows stuff would have it's own checkout under it's own runs-on.

mossy harbor Jun 2, 2023, 9:36 PM

#

the environment or anything like that shouldn't matter

#

the artifact gets uploaded to some place on GitHub

#

and the next job downloads it

#

there doesn't need to be a common environment for that

main swift Jun 2, 2023, 9:38 PM

#

That's the part I'm fuzzy about. So we bounce the artifact through the GitHub ether, how do I get it into the ubuntu environment so that DocFX will be able to see it?

mossy harbor Jun 2, 2023, 9:39 PM

#

it's in the docs that I linked https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts#downloading-artifacts-during-a-workflow-run

GitHub Docs

Storing workflow data as artifacts - GitHub Docs

main swift Jun 2, 2023, 9:39 PM

#

OK, reading FTW!

main swift Jun 2, 2023, 10:15 PM

#

Houston, we have lift off!

#

I've got a combined action that builds the XML, then uses it to buid the DocFx, then uploades that to GitHub Pages!

#

I need to do a bit more testing, and I'll bet we could optimize the push to GitHub Pages. Don't need to push everything in the repo! Other than that, I'd say it seems to be OK

#

📎 message.txt

main swift Jun 3, 2023, 12:33 AM

#

@mossy harbor Where did you get GenDoc? I'd like to be able to link to it here

main swift Jun 3, 2023, 1:06 AM

#

BTW, I've confirmed that updates pushed to the DocFx .md files will trigger an auotmatice rebuild. I'll be testing the effect of pushing updates to the .cs files next, but I don't expect an issue. If it passes that test then I'll move this to finished-projects and we can just use it.

mossy harbor Jun 3, 2023, 2:09 AM

#

main swift <@366972069440913418> Where did you get GenDoc? I'd like to be able to link to i...

I wrote it lol

#

I can put it into a repo

main swift Jun 3, 2023, 2:10 AM

#

LOL! Thanks. Then at least it's correct to say it's open source?

#

BTW, I just pushed up some comments for ManeuverPlanSolver.cs, and the DocFx site is merrily updating. It typically takes 6 - 12 minutes to update when a change is pushed.

#

main swift Jun 3, 2023, 2:21 AM

#

mossy harbor I wrote it lol

Hey, what's the procedure for moving a thread from WIP to Finished? Should I just leave this one here and start a new on there?

mossy harbor Jun 3, 2023, 2:22 AM

#

main swift LOL! Thanks. Then at least it's correct to say it's open source?

https://github.com/jan-bures/GenDoc here you go

GitHub

GitHub - jan-bures/GenDoc: Generate XML documentation from a C# sol...

Generate XML documentation from a C# solution without having to compile the code. - GitHub - jan-bures/GenDoc: Generate XML documentation from a C# solution without having to compile the code.

mossy harbor Jun 3, 2023, 2:23 AM

#

main swift Hey, what's the procedure for moving a thread from WIP to Finished? Should I jus...

sadly there's no feature to move a thread from one forum to another - why Discord wouldn't add it is beyond me

#

so you just have to make a new thread

main swift Jun 3, 2023, 2:24 AM

#

No worries, this one can remain for development... Which may still be needed. I saw the action run for the code doc update I did, but I don't see the impact on the DocFx site...

#

I'm consitently getting success with updates and additions to .md files, but I'm concerned there may still be a hiccup between the GenDoc production og the xml file and the DocFx generation of the site

#

Still, this is like 99% done at least.

#

Also, I'd like to capture the gnerated xml rtifact and put it out as a release from the repo, so there's that

mossy harbor Jun 3, 2023, 2:29 AM

#

https://github.com/marketplace/actions/create-release here's an action you can use as one of the jobs

#

there's an example at the bottom of the page

main swift Jun 3, 2023, 2:35 AM

#

My action has this for on:

on:
  # Runs on pushes targeting the default branch and impacting either the src_stripped, docfx_project, public, or DLL_stripped folders
  push:
    branches: ["main"]
    paths: ["src_stripped/**", "docfx_project/**", "public/**", "DLL_stripped/**"]```
Is there a way to tell if the specific trigger for the action includes any paths in "src_stripped/**"?

#

I'd like to only release a new XML if this is so, but I also want the site to rebuild if any of the other things changed.

main swift Jun 3, 2023, 1:44 PM

#

I'm back to wanting to stuff the new xml into the repo. The issue is that I need a way to know if a new release should be made for the XML file, and what I've got now is basically looking at the file size of the XML since there's an old one up there. We could pull that out and have nothing there until GenDoc puts one there, but how would I know that there is or is not a need to push a new xml file?

#

If the new XML file generated by GenDoc is pushed into the repo, then each time the action runs it can see if what's already in the repo is different than what got made this time.

main swift Jun 3, 2023, 2:59 PM

#

@mossy harbor I'm struggling with correct use of environment variables in the github action. What I've got now mostly works for environment variables with some caveats, but also falls flat on the release with this error.

#

#

What you can see there is that when I get to the push step, I do have working variables for oldSize, newSize, and now. For some reason the file modification time variable is not getting made correctly, but I'm also not using it. My push code looks like this

        if: ${{ env.newSize != env.oldSize }}
      - name: Push Release
        uses: ncipollo/release-action@v1
        with:
          artifacts: "DLL_stripped/Assembly-CSharp.xml"
          body: "* Updated XML Documentation"
          tag: ${{ env.now }}
          commit: true```

#

One weird thing is that when I try to check the environment variables I just get blank lines in the output from the action. So this code

      - name: Compare old Assembly-CSharp.xml to new
        run: |
          ls -l DLL_stripped
          newSize=$(find "DLL_stripped/Assembly-CSharp.xml" -printf "%s")
          echo "newSize=$(find "DLL_stripped/Assembly-CSharp.xml" -printf "%s")" >> "$GITHUB_ENV"
          now=$(date +%Y.%m.%d)
          echo "now=$(date +%Y.%m.%d)" >> "$GITHUB_ENV"
          fileTime=$(find -name "DLL_stripped/Assembly-CSharp.xml" -prune -printf '%TY.%Tm.%Td\n')
          echo "fileTime=$(find -name DLL_stripped/Assembly-CSharp.xml -prune -printf '%TY.%Tm.%Td\n')" >> "$GITHUB_ENV"
          echo "${{ env.newSize }}"
          echo "${{ env.now }}"
          echo "${{ env.fileTime }}"```

#

gives this output

#

#

I've tried it with the code as it is above, and like this

          echo ${{ env.newSize }}
          echo ${{ env.now }}
          echo ${{ env.fileTime }}```
but I get the same result. This may not matter since clearly when I get to the Push step the environment variables are showing up there.

#

I may have found the issue with the 403 error. Looks like I needed to update permission like this.

permissions:
  contents: write
  pages: write
  id-token: write```

#

It had been contents: read

#

testing now

main swift Jun 3, 2023, 4:13 PM

#

Updating the permission did get me further, but now I'm stuck on it not liking the tag I give it. The stupid thing says my tag fails a validation check. The tag is just a string of the data in YYYY.MM.DD format.

#

I'm trying it again with a hard-coded tag of "Initial".

#

I swear to god the morons who wrote that piece of crap should be fired. I tried giving it a perfectly good tag and it gave me this.

#

#

This is not a solution for doing an automated release, it's a solution for doing an automated break of your otherwise perfectly good GitHub action.

main swift Jun 3, 2023, 4:44 PM

#

Problem solved!

#

#

It came down to craptacular documentation and craptacular error messaging. The issue had zip to do with the tag, despite that being the thing it was whining about. It came down to the commit field, which I had mistakenly set to true based on their craptacular documentation. Turns out that needs to be the name of the branch you're committing to. You could have named it branch or something useful. They could have talked about it being used that way where they defined it. Did they? Nope. But if you read between the lines at the bottom of the page there is a clue...

#

Also, I've got the file modification thing sorted and could give this a tag of YYYY.mm.dd.HH.MM.SS if I like.

#

Still have the build-to-build compare problem. It's great that the XML docs are released, but I'm not sure how to compare. Maybe there's a way for the job to fetch the latest release and compare to that?

#

If that works out, then we don't need the XML docs in the repo at all other than as a release.

main swift Jun 3, 2023, 5:05 PM

#

heh, this is curious.

#

I think those two versions should be the same size...

#

Which, of course, caused it to go into the Push Release step... Where we hit this because we don't have it set to overwrite an existing release and the tag is just YYYY.mm.dd. This can be fixed by adding in HH.MM. Don't think we need seconds as the build process itself typically takes several minutes

#

I wonder if the file size difference is some weird Windows vs. Linux thing and the content is actually the same. I pulled down the released XML and stuffed that into my local GitHub clone. It saw no difference with what's online, so I'm thinking comparing file size is not quite working as I'd intended.

#

I need to get a diff output captured somehow. I had a call to diff in there, but it was running, reporting truth, and breaking as it returned a 1 for the files being different which caused that step to think it had failed.

#

Maybe I can spool the diff output into a build.md file that can be used in the release...

#

That would probably need some kind of automated massaging to turn it into something actually good...

rigid plank Jun 4, 2023, 12:11 AM

#

hey @main swift I have linked to your wiki on this wiki for the types, is this ok?
https://github.com/Bit-Studios/konfig/wiki

main swift Jun 4, 2023, 12:15 AM

#

Certainly!

#

Though @finite canopy and @mossy harbor have both suggested that my sight ought to be located in a more common place, so it might move.

#

If it does, then I'll talk about that here, but in the mean time have at it

mossy harbor Jun 4, 2023, 12:17 AM

#

it's up to you, if you wanna move it, we can do it, if not, it's fine

#

don't even need to move the repo, it can stay there and I can just point a *.spacewarp.org subdomain to your GitHub Pages

main swift Jun 4, 2023, 1:07 PM

#

mossy harbor it's up to you, if you wanna move it, we can do it, if not, it's fine

I've been thinking about this and I'm inclined to get it moved over to spacewarp.org. My thoughts here are two fold (yes, I've had two complete thoughts!). First, it would have the appearance of being more "official" within the modding community and may gain higher visibility and better engagement as a result. Second, I'm not sure if you can have more than one GitHub Pages site per account. I could be way off base here, but when I created this one the GitHub guide had me make a repo with my account name. If this is correct, then I'd kind of like to use my GitHub account's GitHub Pages site for a similar documentation effort for my library mods where it would show how to call NodeManager and FlightPlan methods. Those don't belong on a KSP2 API Documentation site, but I could see the use for them.

#

If I'm wrong about that second point that would be good to know. Maybe I can put a FlightPlan docs pages into the FP repo and similarly one for NodeManager? Though I kind of like having a common site with just different "tabs" for the different API's. Might be doable.

finite canopy Jun 4, 2023, 1:11 PM

#

(Okay maybe its not just my internet being fucky)

main swift Jun 4, 2023, 1:13 PM

#

Yeah, my connection is weirdly laggy rn too

finite canopy Jun 4, 2023, 1:13 PM

#

Unless just on my side you double posted that then deleted?

mossy harbor Jun 4, 2023, 1:13 PM

#

seems to be happening for more people

main swift Jun 4, 2023, 1:14 PM

#

I posted once, then there was huge lagg

#

If I'm wrong about that second point that would be good to know. Maybe I can put a FlightPlan docs pages into the FP repo and similarly one for NodeManager? Though I kind of like having a common site with just different "tabs" for the different API's. Might be doable.

#

When it came through I posted another thing, but not a duplicate, got that, then a duplicate appeared

#

Wohhh! Another ghost post!

finite canopy Jun 4, 2023, 1:14 PM

#

Speaking of duplicates

#

Look in #🔴mod-dev for my triple posting

main swift Jun 4, 2023, 1:15 PM

#

If it needs saying it should be said thrice, right?

#

Yeah, my connection is weirdly laggy rn too

finite canopy Jun 4, 2023, 1:17 PM

#

Unless just on my side you double posted that then deleted?

#

Gods discord why are you on crack

mossy harbor Jun 4, 2023, 1:17 PM

#

main swift If I'm wrong about that second point that would be good to know. Maybe I can put...

I would recommend looking at https://www.notion.so/ unless you plan on only generating the documentation for your mods automatically

Notion

Your wiki, docs & projects. Together.

A new tool that blends your everyday work apps into one. It's the all-in-one workspace for you and your team.

main swift Jun 4, 2023, 1:17 PM

#

I deleted the second ghost post

mossy harbor Jun 4, 2023, 1:18 PM

#

finite canopy Unless just on my side you double posted that then deleted?

posted a few minutes ago

main swift Jun 4, 2023, 1:20 PM

#

If it needs saying it should be said thrice, right?

rigid plank Jun 4, 2023, 1:28 PM

#

mossy harbor posted a few minutes ago

oh thats what happened.

main swift Jul 4, 2023, 12:53 PM

#

I've got a /// comment question. When documenting a function that returns a value it's good to put in something like this `/// <returns stateData></returns> or whatever the type of the returned thing is. What about when the returned thing is a List<T> like this?

    /// <summary>
    /// Returns the current list of nodes
    /// </summary>
    /// <returns List\<ManeuverNodeData\>></returns>
    [MethodImpl(MethodImplOptions.NoInlining)]
    public List<ManeuverNodeData> GetNodes() => throw null;

#

Here, I've attempted to escape the < and > around ManeuverNodeData since I don't want that to goof up the tag for the <return>. Is this the right thing to do?

finite canopy Jul 4, 2023, 12:56 PM

#

/// <summary>
/// Returns the current list of nodes
/// </summary>
/// <returns List{ManeuverNodeData}></returns>
[MethodImpl(MethodImplOptions.NoInlining)]
public List<ManeuverNodeData> GetNodes() => throw null;

main swift Jul 4, 2023, 12:57 PM

#

Cool, so it conveys the right info but doesn't goof up the tag. I'll update the docs for how to do this and follow that pattern. Thanks!

mossy harbor Jul 4, 2023, 11:45 PM

#

does that actually exist/mean anything?

#

not as far as I can find https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/documentation-comments#d313-returns

Documentation comments - C# language specification

This appendix describes XML comments that are used to document your program.

#

since you always know the return type because the method has to declare it

#

if you really need to reiterate what it is, the technically correct way would be more like

<returns><see cref="List{ManeuverNodeData}"/></returns>

#

generally in C# documentation comments you rarely ever have to specify the type because that's always known

finite canopy Jul 5, 2023, 12:02 AM

#

I was just giving the correct way to specify type parameters

main swift Jul 5, 2023, 1:06 AM

#

Ahhh, maybe it's waisted time/energy to do that then and it can/should be left blank when vs autogenerates it?

#

If so, that will simplify the instructions for contributing to the docs!

mossy harbor Jul 5, 2023, 1:09 AM

#

yeah, since as you can see, types are just taken from the actual method definitions

#

all you need to provide are human-readable descriptions of the methods/parameters/return values

main swift Jul 5, 2023, 11:08 AM

#

I've updated Step 6 in the AddCodeComments.md file based on what you've said here.
https://github.com/schlosrat/schlosrat.github.io/blob/main/docfx_project/articles/AddCodeComments.md

GitHub

schlosrat.github.io/docfx_project/articles/AddCodeComments.md at ma...

KSP2 Unofficial API. Contribute to schlosrat/schlosrat.github.io development by creating an account on GitHub.

#

I'll probably also go back and remove all the incorrectly documented stuff I put in for that. Not a huge chore, and worth doing.

#KSP2 API DocFX Project