Add docfx documentation #985

nitanmarcel · 2021-03-02T00:49:08Z

An year-ish ago I've made a small issue speaking about a documentation website for the library generated using Doxygen #918 and since then I forgot about it, oops.

Anyway, using Doxygen for the documentation wasn't such a good idea since the generated HTML files needed some changes to display as they should be.

A couple of days ago I found DocFx and I remembered about the documentation I've made for the library before.

The documentation is generated by DocFx each time a new tag is released which means it won't be available after merging it unless there's a new tag after the merge (the tag needs to start with v3 and also the gh-pages branch needs to be set as the main branch for GitHub pages) . But you can still test the theme here: https://nitanmarcel.github.io/scripthookvdotnet/index.html until it will be on this repo.

I'm using GitHub Actions to set up the documentation and it works in the following way:

If a new tag who's string matches "v3*" (eg. v3.1.1, v3.1.2, v3.x.x) will be release the workflow will start generating the documentation.

I tried to auto-generate everything that I could auto-generate starting from the index page which uses the README file, up to the changelog page which uses https://github.com/heinrichreimer/action-github-changelog-generator which generates changelog data between each available tag in a nicely printed way: eg. https://github.com/skywinder/ActionSheetPicker-3.0/blob/develop/CHANGELOG.md

The workflow will take care of everything except for deploying the GitHub page for the first time. It still requires a one-time activation from GitHub's repository settings. But after the workflow finished pushing the documentation to the gh-pages branch.

crosire

This is really cool!
Do you still have links to where the template used came from? And would it maybe be possible to embed that somehow without adding all the files to this repository (e.g. via a submodule or just fetching it as part of the actions script)?

crosire · 2021-03-02T17:53:04Z

doc/docfx.json

+                    "scripting_v2/**.yml",
+                    "scripting_v3/**.yml",
+                    "scripting_v2/api/**.yml",
+                    "scripting_v3/api**.yml"


This looks unintentional (/ missing)?

Nope. DocFX uses glob for the paths so /scripthook_vx/ will point to /system-root/scripthook_vx

I mean you have one line
"scripting_v2/api/**.yml"
and then
"scripting_v3/api**.yml"
which is inconsistent?

Why not just do:
scripting_v*/**.yml and scripting_v*/api/**.yml to cover v2, v3, and any other future versions all in a single go?

crosire · 2021-03-02T17:53:50Z

doc/scripting_v3/index.md

@@ -0,0 +1,4 @@
+ScriptHookVDotNet v2


v3, not v2 =)

Oh, my bad. I noticed this I had like over 30 commits and I kept reverting them when things went wrong and I might delete the one that modified this

doc/scripting_v2/index.md

doc/docfx.json

doc/template/darkfx/partials/affix.tmpl.partial

nitanmarcel

This is really cool!
Do you still have links to where the template used came from? And would it maybe be possible to embed that somehow without adding all the files to this repository (e.g. via a submodule or just fetching it as part of the actions script)?

https://github.com/steffen-wilke/darkfx

In the second part you mean without adding the doc directory here? I could simply make my own repo with the doc folder and clone it using GitHub actions

nitanmarcel · 2021-03-02T18:57:09Z

doc/docfx.json

+                    "scripting_v2/**.yml",
+                    "scripting_v3/**.yml",
+                    "scripting_v2/api/**.yml",
+                    "scripting_v3/api**.yml"


Nope. DocFX uses glob for the paths so /scripthook_vx/ will point to /system-root/scripthook_vx

nitanmarcel · 2021-03-02T20:31:37Z

@crosire I'm preparing a separate branch for the documentation so we can add it as a submodule or if you want or I'll clone it from inside github actions. ~~I'll wait for an answer ^^~~

nitanmarcel · 2021-03-02T21:39:52Z

I've added the documentation as a submodule: https://github.com/nitanmarcel/scripthookvdotnet-doc which is a fork of the template used on the documentation.

Also I did some changes. The main page uses the Getting Started wiki page and the footer contains a link to the license which now will be generated as part of the website

Index

License

Added some more generated filesto .gitignore in case the documentation is generated locally

crosire · 2021-03-03T00:06:03Z

Ah, sorry 🙃, I didn't mean it that drastic, was thinking that the template could have been a submodule to avoid adding all these files that have no relation to SHVDN. So a directory structure like this:

- docs
   - docfx.json
   - index.md
   - toc.yml
   - scripting_v2/
      - index.md
   - scripting_v3/
      - index.md
   - templates/
      - darkfx/ submodule pointing towards https://github.com/steffen-wilke/darkfx (since you can have Git submodules in sub directories, see "-path" argument to git submodule add)
      - memberpage/ submodule pointing towards where that came from

While adding the entire docs as a submodule may be advantageous too, the problem I'm seeing is that it breaks the link between the GitHub Actions script and the docs content. So would be better to keep those close together I think.

nitanmarcel · 2021-03-03T09:54:24Z

Ah, sorry 🙃, I didn't mean it that drastic, was thinking that the template could have been a submodule to avoid adding all these files that have no relation to SHVDN. So a directory structure like this:
- docs
   - docfx.json
   - index.md
   - toc.yml
   - scripting_v2/
      - index.md
   - scripting_v3/
      - index.md
   - templates/
      - darkfx/ submodule pointing towards https://github.com/steffen-wilke/darkfx (since you can have Git submodules in sub directories, see "-path" argument to git submodule add)
      - memberpage/ submodule pointing towards where that came from
While adding the entire docs as a submodule may be advantageous too, the problem I'm seeing is that it breaks the link between the GitHub Actions script and the docs content. So would be better to keep those close together I think.

Ok, I'll see what I can do about it. Also the memberspage is a nuget package and I don't think it's built in in docfx like the default template but I will check :)

chakibchemso · 2021-07-20T22:47:07Z

Awesome work!!!

nitanmarcel · 2021-07-21T09:24:40Z

Awesome work!!!

Thanks. Anyway this will be pushed forward because I'm waiting for docFX v3 to come stable

kagikn · 2023-06-03T16:29:47Z

I didn't care about web documentation too much until I received full access to do what I want without external approvals, but now it's good time for me to make a proper web documentation since we'll officially deprecate the v2 SDK/API in v3.7.0 (3.5 year passed since the first v3 release though). I'll make another PR when I create the official web docs.

I heard Lemon got annoyed for not a few people asking for how to use LemonUI in scripts built against v2 API (not v3), and I'm disappointed at the fact a lot of people (maybe more than the half of script devs on 5mods?) use v2 SDK/API for new scripts even they don't reference to other scripts built against v2 API, too. I'll be willing to create the official web documentation for API(s) if more people will have their scripts migrate to v3 SDK/API.

nitanmarcel · 2023-06-06T07:28:34Z

I totally forgot this existed. Oups xD

Add docfx documentation

0760495

crosire reviewed Mar 2, 2021

View reviewed changes

nitanmarcel commented Mar 2, 2021

View reviewed changes

nitanmarcel added 5 commits March 2, 2021 21:10

Fix index.md in doc/scripting_v2 and doc/scripting_v2

15201f5

Remove unused docfx.json keys

65985a2

Fix footer

c630bff

Disable Contribution links

c661f7b

Change app's title

f87e1dd

nitanmarcel added 2 commits March 2, 2021 23:25

Use the documentation as a submodule

40d0d91

Also checkout submodules

1d068a4

Update documentation submodule

9f2c2bd

Added some more generated filesto .gitignore in case the documentation is generated locally

kagikn force-pushed the main branch 6 times, most recently from 7f69174 to 07f22e7 Compare October 16, 2024 12:56

kagikn force-pushed the main branch from e0d42a7 to 4fbb47e Compare November 15, 2024 11:29

Uh oh!

Add docfx documentation #985

Are you sure you want to change the base?

Add docfx documentation #985

Uh oh!

Conversation

nitanmarcel commented Mar 2, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

crosire left a comment

Choose a reason for hiding this comment

Uh oh!

crosire Mar 2, 2021

Choose a reason for hiding this comment

Uh oh!

nitanmarcel Mar 2, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crosire Mar 2, 2021

Choose a reason for hiding this comment

Uh oh!

AraHaan Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

crosire Mar 2, 2021

Choose a reason for hiding this comment

Uh oh!

nitanmarcel Mar 2, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nitanmarcel left a comment

Choose a reason for hiding this comment

Uh oh!

nitanmarcel Mar 2, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nitanmarcel commented Mar 2, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nitanmarcel commented Mar 2, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

crosire commented Mar 3, 2021

Uh oh!

nitanmarcel commented Mar 3, 2021

Uh oh!

chakibchemso commented Jul 20, 2021

Uh oh!

nitanmarcel commented Jul 21, 2021

Uh oh!

kagikn commented Jun 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nitanmarcel commented Jun 6, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nitanmarcel commented Mar 2, 2021 •

edited

Loading

nitanmarcel Mar 2, 2021 •

edited

Loading

nitanmarcel Mar 2, 2021 •

edited

Loading

nitanmarcel commented Mar 2, 2021 •

edited

Loading

nitanmarcel commented Mar 2, 2021 •

edited

Loading

kagikn commented Jun 3, 2023 •

edited

Loading