From 6a20d96bb58bce287328131ddc3f578f874e3cf7 Mon Sep 17 00:00:00 2001 From: AURUMVORXX Date: Mon, 4 Nov 2024 05:09:59 +0300 Subject: [PATCH] feat: Added docs via MkDocs --- .github/workflows/docs_pages.yml | 21 ++++++ .gitlab-ci.yml | 7 -- CMakeLists.txt | 2 + docs/defaultEvents/onBan.md | 27 ++++++++ docs/defaultEvents/onExit.md | 15 +++++ docs/defaultEvents/onInit.md | 14 ++++ docs/defaultEvents/onTick.md | 14 ++++ docs/defaultEvents/onTime.md | 20 ++++++ docs/defaultEvents/onUnban.md | 23 +++++++ docs/docs/assets/logo.png | Bin 1667 -> 0 bytes docs/docs/index.md | 3 - docs/docs/stylesheets/extra.css | 7 -- docs/events/addEvent.md | 2 + docs/events/callEvent.md | 2 + docs/events/event.md | 2 + docs/events/removeEventHandler.md | 2 + docs/index.md | 1 + docs/mkdocs.yml | 37 ----------- docs/requirements.txt | 3 - g2o/events.py | 103 ++++++++++++++++++++++++++++-- mkdocs.yml | 57 +++++++++++++++++ 21 files changed, 299 insertions(+), 63 deletions(-) create mode 100644 .github/workflows/docs_pages.yml delete mode 100644 .gitlab-ci.yml create mode 100644 docs/defaultEvents/onBan.md create mode 100644 docs/defaultEvents/onExit.md create mode 100644 docs/defaultEvents/onInit.md create mode 100644 docs/defaultEvents/onTick.md create mode 100644 docs/defaultEvents/onTime.md create mode 100644 docs/defaultEvents/onUnban.md delete mode 100644 docs/docs/assets/logo.png delete mode 100644 docs/docs/index.md delete mode 100644 docs/docs/stylesheets/extra.css create mode 100644 docs/events/addEvent.md create mode 100644 docs/events/callEvent.md create mode 100644 docs/events/event.md create mode 100644 docs/events/removeEventHandler.md create mode 100644 docs/index.md delete mode 100644 docs/mkdocs.yml delete mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.github/workflows/docs_pages.yml b/.github/workflows/docs_pages.yml new file mode 100644 index 0000000..0abe2ea --- /dev/null +++ b/.github/workflows/docs_pages.yml @@ -0,0 +1,21 @@ +name: docs + +on: + push: + branches: + - main + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - run: | + pip install mkdocs + pip install "mkdocstrings[python]" + pip install mkdocs-material + pip install mkdocs-callouts + mkdocs gh-deploy --force \ No newline at end of file diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml deleted file mode 100644 index 8bca609..0000000 --- a/.gitlab-ci.yml +++ /dev/null @@ -1,7 +0,0 @@ -include: - - project: GothicMultiplayerTeam/templates - file: [squirrel-module.yml] - -variables: - PROJECT_NAME: ${CI_PROJECT_NAME} - VERSION: "0.1" \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index cac8cea..a80a16f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -66,6 +66,8 @@ file(GLOB_RECURSE SOURCE "src/*.h" "src/*.cpp" + "src/events/*.h" + "src/events/*.cpp" ) # Linking directories diff --git a/docs/defaultEvents/onBan.md b/docs/defaultEvents/onBan.md new file mode 100644 index 0000000..4593f39 --- /dev/null +++ b/docs/defaultEvents/onBan.md @@ -0,0 +1,27 @@ +# `event` onBan +!!! note + If serial/mac/ip/name indexes doesn't exist, then the parameters has not been specified when ban was added. + If timestamp doesn't exist, then ban was permanent. + +This event is triggered when new ban is being added. + +## Parameters +* `dict` **kwargs**: + * `str` **mac**: MAC address of the banned player. + * `str` **ip**: IP address of the banned player. + * `str` **serial**: serial of the banned player. + * `str` **name**: nickname of the banned player. + * `int` **timestamp**: timestamp when the ban expires. + +## Usage +```python +import g2o +from datetime import datetime + +@g2o.event('onBan') +def onBan(**kwargs): + print(f'Player {kwargs['name']} has been banned.') + if ('timestamp' in kwargs): + banExpires = datetime.fromtimestamp(kwargs['timestamp']) + print(f'Ban expires at {banExpires}') +``` \ No newline at end of file diff --git a/docs/defaultEvents/onExit.md b/docs/defaultEvents/onExit.md new file mode 100644 index 0000000..a52b53f --- /dev/null +++ b/docs/defaultEvents/onExit.md @@ -0,0 +1,15 @@ +# `event` onExit +This event is triggered when server is going to shut down. +You can use it, to save some data before closing up, or do something else. + +## Parameters +No parameters. + +## Usage +```python +import g2o + +@g2o.event('onExit') +def onExitEvt(**kwargs): + print('Bye') +``` \ No newline at end of file diff --git a/docs/defaultEvents/onInit.md b/docs/defaultEvents/onInit.md new file mode 100644 index 0000000..775edd1 --- /dev/null +++ b/docs/defaultEvents/onInit.md @@ -0,0 +1,14 @@ +# `event` onInit +This event is triggered when server successfully starts up. + +## Parameters +No parameters. + +## Usage +```python +import g2o + +@g2o.event('onInit') +def onInitEventHandler(**kwargs): + print('Called onInit event') +``` \ No newline at end of file diff --git a/docs/defaultEvents/onTick.md b/docs/defaultEvents/onTick.md new file mode 100644 index 0000000..9f843ac --- /dev/null +++ b/docs/defaultEvents/onTick.md @@ -0,0 +1,14 @@ +# `event` onTick +This event is triggered in every server main loop iteration. + +## Parameters +No parameters. + +## Usage +```python +import g2o + +@g2o.event('onTick') +def onTickEvt(**kwargs): + print('Tock') +``` \ No newline at end of file diff --git a/docs/defaultEvents/onTime.md b/docs/defaultEvents/onTime.md new file mode 100644 index 0000000..fe63a81 --- /dev/null +++ b/docs/defaultEvents/onTime.md @@ -0,0 +1,20 @@ +# `event` onTime +This event is triggered each time when game time minute passes. + +## Parameters +* `dict` **kwargs**: + * `int` **day**: the current ingame day. + * `int` **hour**: the current ingame hour. + * `int` **min**: the current ingame minutes. + +## Usage +```python +import g2o + +@g2o.event('onTick') +def onTickEvt(**kwargs): + day = kwargs['day'] + hour = kwargs['hour'] + mins = kwargs['min'] + print(f'Current time: Day {day}, Hour {hour}, Min {mins}') +``` \ No newline at end of file diff --git a/docs/defaultEvents/onUnban.md b/docs/defaultEvents/onUnban.md new file mode 100644 index 0000000..2b6192f --- /dev/null +++ b/docs/defaultEvents/onUnban.md @@ -0,0 +1,23 @@ +# `event` onUnban +!!! note + If serial/mac/ip/name indexes doesn't exist, then the parameters has not been specified when ban was added. + If timestamp doesn't exist, then ban was permanent. + +This event is triggered when ban with specified info is being removed. + +## Parameters +* `dict` **kwargs**: + * `str` **mac**: MAC address of the banned player. + * `str` **ip**: IP address of the banned player. + * `str` **serial**: serial of the banned player. + * `str` **name**: nickname of the banned player. + * `int` **timestamp**: timestamp when the ban expires. + +## Usage +```python +import g2o + +@g2o.event('onUnban') +def onUnban(**kwargs): + print(f'Player {kwargs['name']} has been unbanned.') +``` \ No newline at end of file diff --git a/docs/docs/assets/logo.png b/docs/docs/assets/logo.png deleted file mode 100644 index b1a7447c6ea13b4e2edfc6ec39c08a3a02793e51..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1667 zcmV-}27LL6P)Zb9OqN=W<u6kYu@|UY z0jL~A0Qdsey1HU6K&J}VT>xJUSCO~1x&OJS0RGfaK;o|o_ml#Maj!l%XRHKn)f|v` zcC#jo#;72G83zE0@U?t))!cbXQvfO$zZ(Xh^c*oF0C~S-_F|*G{>;(d(Xsn-HFrX1 zrDHz~bx{eg=7h)8FuJ_n-bwg-U;l(3w|6$C=H`rhL3h$5oSN(a&j^ncK&yU}3%<)8 z>ruv@Ml(mm405ymTIndm%;-_kAkLNnFbNxC+!T8xJX%&;BKe-DbjUU_1DlBnalq(z zBK=WcX{FfDO?kyTM%gr{y%%rOFA;GJ;GfHe(=uBn3Nrvd)e3isf!jL?zVf+E3{nTJ zW~ftubBux*M1=lk2isdc|M{d8j7~!zDYEHq41T@osk`L9f>Vxtga#PR#QD)Iwpg zFf_AY(=eZ%2a5pInP*h7h{SdUq6``Kp&~|-#C<(emtb@ibjo9{Tx7H?Bh3Rai+OIf zt%f5gVVDYxHQI-b7;jAT)~Yi8S|`Gdep^N2vCQ3CmXYSM(3#95p322zMA+p@^pdm?4QXCp5_0%V56ptv@nT7*XcYXvS$a6z%OPD(lo<(oHlNTg{gYo4tl+= z4?o!n(H%CFYU`dEl#2kgL$98QV_H@rCxyZhhM9wE8ZUJK#Ap=`d0u#Zt;nDiX|!W4 zyDVN$YBn?mP@#ST;17}mY0fwIUuV0cocTt-r9Sgvg1n%{F+W*=2(6@pIO+PhfBI^G zf4@5BPRpoaM*D$%;$Q>j?Zm?6C1FEd`XS(3-t4>I{8W7Z+n>j?!?9=>qGCw^ zTxKd$0d~>^I*e_MR3#XWGAOXmE2%4mqb@O9B8meW%|)>YfRunD)EWs}{{;di)mUS( z_|C3?>GWZeZD@9I8K8!)q_@BlVTi$nkj7cYF9YD*L}?8-9-;TyuVL#8-|ztFAAiE( z-yTBg?#g;E4L~Uh>~c_c46yT`*F9;uWB^smsmr8TgN7?JVMrpm^1#$qr14n$-&1oe0Cw*rj>%dLYk9@#<|v*y_ZvS}k3?ngTdg)Lswro4@dhcsx_H&4k>A>p#yIz^HYsY~ zxw8}B|JEL!9i@;uF?S(t;KuK;xpxQ2r@xBrehc6K@z3$I2fv&uUU6iQv|zMC(u(COTxyGQjdOb^u8ZWGFKPub zDHp0+gDh6cARE2I`-7*ju8r~VoljtC=3Lp27sR}L!FzxOVs3&0B|_Xa4_1y#tCfPhBoUje<=V67NjgRtU&M{_g-J8hy+>p_kpUY zXxzN`Aypa1dI%lJ#S!zhZfoV@buQBS@0-{U!qLkxT$dTuz49z# zyZUd9tA>!y9n03IMyu=L3^Qr)e4^y-jQP4FwuPfsI8JQLr>g>xoX!04KJjA!55sR? z(UQ;S0L#6PL-A6p82^7E=TQfA!=9=x^s)7PC0G8xRjxdM{{#R4|Nm#OQF+@#Eu;Vd N002ovPDHLkV1kd>IvfB1 diff --git a/docs/docs/index.md b/docs/docs/index.md deleted file mode 100644 index 1ab2f5c..0000000 --- a/docs/docs/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Home - -An example README that you can replace with your own content! \ No newline at end of file diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css deleted file mode 100644 index 492b119..0000000 --- a/docs/docs/stylesheets/extra.css +++ /dev/null @@ -1,7 +0,0 @@ -:root { - --md-primary-fg-color: #8191ff; -} - -.md-header { - background-color: #232323; -} \ No newline at end of file diff --git a/docs/events/addEvent.md b/docs/events/addEvent.md new file mode 100644 index 0000000..a93b05c --- /dev/null +++ b/docs/events/addEvent.md @@ -0,0 +1,2 @@ +# `function` addEvent +::: g2o.events.addEvent \ No newline at end of file diff --git a/docs/events/callEvent.md b/docs/events/callEvent.md new file mode 100644 index 0000000..207cd08 --- /dev/null +++ b/docs/events/callEvent.md @@ -0,0 +1,2 @@ +# `function` callEvent +::: g2o.events.callEvent \ No newline at end of file diff --git a/docs/events/event.md b/docs/events/event.md new file mode 100644 index 0000000..915b3ad --- /dev/null +++ b/docs/events/event.md @@ -0,0 +1,2 @@ +# `function` event +::: g2o.events.event \ No newline at end of file diff --git a/docs/events/removeEventHandler.md b/docs/events/removeEventHandler.md new file mode 100644 index 0000000..c993332 --- /dev/null +++ b/docs/events/removeEventHandler.md @@ -0,0 +1,2 @@ +# `function` removeEventHandler +::: g2o.events.removeEventHandler \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..ad08ae1 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +# Blank \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml deleted file mode 100644 index 298a997..0000000 --- a/docs/mkdocs.yml +++ /dev/null @@ -1,37 +0,0 @@ -site_name: Squirrel Template Module - Docs -repo_url: https://gitlab.com/GothicMultiplayerTeam/modules/squirrel-template -repo_name: Squirrel Template Module -edit_uri: "" -site_dir: "public" - -extra_css: - - stylesheets/extra.css - -extra: - version: - provider: mike - -markdown_extensions: - - admonition - - attr_list - - pymdownx.tabbed - - pymdownx.highlight - - pymdownx.superfences - -theme: - name: material - logo: assets/logo.png - icon: - repo: fontawesome/brands/gitlab - palette: - - media: "(prefers-color-scheme: light)" - scheme: default - toggle: - icon: material/eye-outline - name: Switch to dark mode - - - media: "(prefers-color-scheme: dark)" - scheme: slate - toggle: - icon: material/eye - name: Switch to light mode diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 01b75d6..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -mkdocs==1.5.3 -mkdocs-material==9.5.12 -mike==2.0.0 \ No newline at end of file diff --git a/g2o/events.py b/g2o/events.py index b5a48f6..d8dea51 100644 --- a/g2o/events.py +++ b/g2o/events.py @@ -1,16 +1,84 @@ eventList = {} -def callEvent(name : str, **args : dict): - if name in eventList: - for event in eventList[name]: - event['function'](**args) +def callEvent(evtName : str, **kwargs : dict): + """ + This function will notify (call) every handler bound to specified event. + Original: [callEvent](https://gothicmultiplayerteam.gitlab.io/docs/0.3.0/script-reference/shared-functions/event/callEvent/) + + ## Declaration + ```python + def callEvent(evtName : str, **kwargs : dict) + ``` + + ## Parameters + * `str` **name**: the name of the event + * `**dict` **kwargs**: the variable number of arguments. + + ## Usage + ```python + import g2o + + g2o.addEvent('testEvt') + + @g2o.event('testEvt') + def onTestEvent(**kwargs): + print(f'{kwargs['name']} called my beautiful test event') + + g2o.callEvent('testEvt', name = 'Diego') + ``` + """ + if evtName in eventList: + for event in eventList[evtName]: + event['function'](**kwargs) def addEvent(name): + """ + This function will register a new event with specified name. + Events can be used to notify function(s) when something will happen, like player joins the server, etc. + Original: [addEvent](https://gothicmultiplayerteam.gitlab.io/docs/0.3.0/script-reference/shared-functions/event/addEvent/) + + ## Declaration + ```python + def addEvent(name) + ``` + + ## Parameters + * `str` **name**: the name of the event + + ## Usage + ```python + import g2o + + g2o.addEvent('testEvt') + ``` + """ if not name in eventList: eventList[name] = [] def event(name : str, priority : int = 9999): + """ + This function will bind function to specified event. + Original: [addEventHandler](https://gothicmultiplayerteam.gitlab.io/docs/0.3.0/script-reference/shared-functions/event/addEventHandler/) + + ## Declaration + ```python + def event(name : str, priority : int = 9999) + ``` + + ## Parameters + * `str` **name**: the name of the event + * `int` **priority**: the function priority. The lower the value, the sooner the function/handler will be called. + + ## Usage + ```python + import g2o + + @g2o.event('onInit') + def onInitEventHandler(**kwargs): + print('Called onInit event') + ``` + """ def inlineEvt(func): if not name in eventList: pass @@ -20,7 +88,30 @@ def event(name : str, priority : int = 9999): return func return inlineEvt -def removeEventHandler(name : str, func : int): +def removeEventHandler(name : str, func : function): + """ + This function will unbind function from specified event. + Original: [removeEventHandler](https://gothicmultiplayerteam.gitlab.io/docs/0.3.0/script-reference/shared-functions/event/removeEventHandler/) + + ## Declaration + ```python + def removeEventHandler(name : str, func : function) + ``` + + ## Parameters + * `str` **name**: the name of the event + * `function` **func**: the reference to a function which is currently bound to specified event. + + ## Usage + ```python + import g2o + + @g2o.event('onTime') + def onTimeEvt(**kwargs): + print('Calling only once') + g2o.removeEventHandler('onTime', onTimeEvt) + ``` + """ if not name in eventList: pass @@ -28,7 +119,7 @@ def removeEventHandler(name : str, func : int): if item['function'] == func: del eventList[name][index] -## registering all events +## registering default events addEvent('onInit') addEvent('onExit') diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..103fec0 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,57 @@ +site_name: PyG2O + +markdown_extensions: + - nl2br + - admonition + - pymdownx.details + - pymdownx.superfences + - sane_lists + +plugins: + - mkdocstrings + - search + - callouts + +repo_url: https://github.com/AURUMVORXX/PyG2O.git + +nav: + - Home: index.md + - Events: + - General: + - onInit: defaultEvents/onInit.md + - onExit: defaultEvents/onExit.md + - onTick: defaultEvents/onTick.md + - onTime: defaultEvents/onTime.md + - onBan: defaultEvents/onBan.md + - onUnban: defaultEvents/onUnban.md + - Functions: + - Events: + - event: events/event.md + - removeEventHandler: events/removeEventHandler.md + - addEvent: events/addEvent.md + - callEvent: events/callEvent.md + +theme: + name: material + features: + - search.suggest + - search.highlight + - content.tabs.link + - content.code.annotation + - content.code.copy + icon: + repo: fontawesome/brands/gitlab + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/eye-outline + name: Switch to dark mode + + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/eye + name: Switch to light mode + + primary: black \ No newline at end of file