diff --git a/.github/AUTODOC_GUIDE.md b/.github/AUTODOC_GUIDE.md new file mode 100644 index 00000000000..6a7d521a04d --- /dev/null +++ b/.github/AUTODOC_GUIDE.md @@ -0,0 +1,108 @@ +# dmdoc +[DOCUMENTATION]: https://codedocs.paradisestation.org/ + +[BYOND]: https://secure.byond.com/ + +[DMDOC]: https://github.com/AffectedArc07/ParaSpacemanDMM/tree/master/src/dmdoc + +[DMDOC] is a documentation generator for DreamMaker, the scripting language +of the [BYOND] game engine. It produces simple static HTML files based on +documented files, macros, types, procs, and vars. + +We use **dmdoc** to generate [DOCUMENTATION] for our code, and that documentation +is automatically generated and built on every new commit to the master branch + +This gives new developers a clickable reference [DOCUMENTATION] they can browse to better help +gain understanding of the Paradise codebase structure and api reference. + +## Documenting code on Paradise +We use block comments to document procs and classes, and we use `///` line comments +when documenting individual variables. + +Documentation is not required at Paradise, but it is highly recommended that all new code be covered with DMdoc code, according to the [Specifications](#Specification) + +We also recommend that when you touch older code, you document the functions that you +have touched in the process of updating that code + +### Specification +A class *should* always be autodocumented, and all public functions *should* be documented + +All class level defined variables *should* be documented + +Internal functions *can* be documented, but may not be + +A public function is any function that a developer might reasonably call while using +or interacting with your object. Internal functions are helper functions that your +public functions rely on to implement logic + + +### Documenting a proc +When documenting a proc, we give a short one line description (as this is shown +next to the proc definition in the list of all procs for a type or global +namespace), then a longer paragraph which will be shown when the user clicks on +the proc to jump to it's definition +``` +/** + * Short description of the proc + * + * Longer detailed paragraph about the proc + * including any relevant detail + * Arguments: + * * arg1 - Relevance of this argument + * * arg2 - Relevance of this argument + */ +``` + +### Documenting a class +We first give the name of the class as a header, this can be omitted if the name is +just going to be the typepath of the class, as dmdoc uses that by default + +Then we give a short oneline description of the class + +Finally we give a longer multi paragraph description of the class and it's details +``` +/** + * # Classname (Can be omitted if it's just going to be the typepath) + * + * The short overview + * + * A longer + * paragraph of functionality about the class + * including any assumptions/special cases + * + */ +``` + +### Documenting a variable/define +Give a short explanation of what the variable, in the context of the class, or define is. +``` +/// Type path of item to go in suit slot +var/suit = null +``` + +## Module level description of code +Modules are the best way to describe the structure/intent of a package of code +where you don't want to be tied to the formal layout of the class structure. + +On Paradise we do this by adding markdown files inside the `code` directory +that will also be rendered and added to the modules tree. The structure for +these is deliberately not defined, so you can be as freeform and as wheeling as +you would like. + +[Here is a representative example of what you might write](https://codedocs.paradisestation.org/code/modules/keybindings/readme.html) + +## Special variables +You can use certain special template variables in DM DOC comments and they will be expanded +``` + [DEFINE_NAME] - Expands to a link to the define definition if documented + [/mob] - Expands to a link to the docs for the /mob class + [/mob/proc/Dizzy] - Expands to a link that will take you to the /mob class and anchor you to the dizzy proc docs + [/mob/var/stat] - Expands to a link that will take you to the /mob class and anchor you to the stat var docs +``` + +You can customise the link name by using `[link name][link shorthand].` + +eg. `[see more about dizzy here] [/mob/proc/Dizzy]` + +This is very useful to quickly link to other parts of the autodoc code to expand +upon a comment made, or reasoning about code diff --git a/.github/workflows/generate_autodoc.yml b/.github/workflows/generate_autodoc.yml new file mode 100644 index 00000000000..44eb69eb570 --- /dev/null +++ b/.github/workflows/generate_autodoc.yml @@ -0,0 +1,32 @@ +name: Generate Documentation + +on: + schedule: + - cron: "0 0 * * *" # Every day at the very start of the day + +jobs: + generate_docs: + name: 'Generate Documentation' + runs-on: ubuntu-18.04 + steps: + - name: 'Update Branch' + uses: actions/checkout@v2 + with: + fetch-depth: 1 + ref: master + + - name: 'Generate Documentation' + run: | + ./tools/github-actions/doc-generator + touch dmdoc/.nojekyll + # Nojekyll is important to disable jeykll syntax, which can mess with files that start with underscores + + - name: 'Deploy Documentation' + uses: crazy-max/ghaction-github-pages@v2 + with: + keep_history: false + build_dir: dmdoc + jekyll: false + fqdn: codedocs.paradisestation.org + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/tools/github-actions/README.MD b/tools/github-actions/README.MD index 74b31f5bdd6..b6a3542a884 100644 --- a/tools/github-actions/README.MD +++ b/tools/github-actions/README.MD @@ -4,3 +4,4 @@ This folder contains all the script and tools required for GitHub actions. If yo - `nanomap-renderer` - A linux application to render NanoMap images of the ingame maps automatically. Based off of SpacemanDMM (Modified source [here](https://github.com/AffectedArc07/ParaSpacemanDMM), original source [here](https://github.com/Spacemaniac/SpacemanDMM)) - `nanomap-renderer-invoker.sh` - A script which invokes the render tool and clones the maps to the correct directory +- `doc-generator` - A linux application to generate documentation of game code automatically. Based off of SpacemanDMM (Modified source [here](https://github.com/AffectedArc07/ParaSpacemanDMM), original source [here](https://github.com/Spacemaniac/SpacemanDMM)) diff --git a/tools/github-actions/doc-generator b/tools/github-actions/doc-generator new file mode 100644 index 00000000000..ce0b4fa25f5 Binary files /dev/null and b/tools/github-actions/doc-generator differ