mirrors/CC-Tweaked
1
0
Fork 0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2024-12-12 03:00:30 +00:00
Code Issues Releases Wiki Activity
9d1ee6f61d
CC-Tweaked/illuaminate.sexp

124 lines
3.5 KiB
Plaintext
Raw Normal View History

Lint bios and the rom (#321) We now use illuaminate[1]'s linting facilities to check the rom and bios.lua for a couple of common bugs and other problems. Right now this doesn't detect any especially important bugs, though it has caught lots of small things (unused variables, some noisy code). In the future, the linter will grow in scope and features, which should allow us to be stricter and catch most issues. As a fun aside, we started off with ~150 bugs, and illuaminate was able to fix all but 30 of them, which is pretty neat. [1]: https://github.com/SquidDev/illuaminate
2019-12-03 23:26:13 +00:00
; -*- mode: Lisp;-*-
(sources
An initial stab at documentation generation (#360) This adds documentation comments to many of CC's Lua APIs, and a couple of the Java ones, through the use of stubs. We then export these to HTML using illuaminate [1] and upload them to our documentation site [2]. Uploads currently occur on pushes to master and any release/tag. The site is entirely static - there is no way to switch between versions, etc... but hopefully we can improve this in the future. [1]: github.com/SquidDev/illuaminate/ [2]: https://tweaked.cc/
2020-04-10 09:27:53 +00:00
/doc/stub/
Add some initial documentation for events Credit to @BradyFromDiscord for writing these. See #640 and #565. Co-authored-by: Brady <bradyakent@gmail.com
2021-01-14 18:19:22 +00:00
/doc/events/
Runnable examples (#576) Provides a basic interface for running examples on tweaked.cc. This is probably janky as anything, but it works on my machine. This is the culmination of 18 months of me building far too much infrastructure (copy-cat, illuaminate), so that's nice I guess. I should probably get out more.
2020-11-12 19:01:50 +00:00
/build/docs/luaJavadoc/
Add documentation for shell and multishell Heh, one place we're more complete than cc.cc :p.
2020-04-22 13:39:39 +00:00
/src/main/resources/*/computercraft/lua/bios.lua
/src/main/resources/*/computercraft/lua/rom/
Runnable examples (#576) Provides a basic interface for running examples on tweaked.cc. This is probably janky as anything, but it works on my machine. This is the culmination of 18 months of me building far too much infrastructure (copy-cat, illuaminate), so that's nice I guess. I should probably get out more.
2020-11-12 19:01:50 +00:00
/src/test/resources/test-rom
/src/web/mount)
Lint bios and the rom (#321) We now use illuaminate[1]'s linting facilities to check the rom and bios.lua for a couple of common bugs and other problems. Right now this doesn't detect any especially important bugs, though it has caught lots of small things (unused variables, some noisy code). In the future, the linter will grow in scope and features, which should allow us to be stricter and catch most issues. As a fun aside, we started off with ~150 bugs, and illuaminate was able to fix all but 30 of them, which is pretty neat. [1]: https://github.com/SquidDev/illuaminate
2019-12-03 23:26:13 +00:00
An initial stab at documentation generation (#360) This adds documentation comments to many of CC's Lua APIs, and a couple of the Java ones, through the use of stubs. We then export these to HTML using illuaminate [1] and upload them to our documentation site [2]. Uploads currently occur on pushes to master and any release/tag. The site is entirely static - there is no way to switch between versions, etc... but hopefully we can improve this in the future. [1]: github.com/SquidDev/illuaminate/ [2]: https://tweaked.cc/
2020-04-10 09:27:53 +00:00
(doc
Runnable examples (#576) Provides a basic interface for running examples on tweaked.cc. This is probably janky as anything, but it works on my machine. This is the culmination of 18 months of me building far too much infrastructure (copy-cat, illuaminate), so that's nice I guess. I should probably get out more.
2020-11-12 19:01:50 +00:00
(destination build/docs/lua)
An initial stab at documentation generation (#360) This adds documentation comments to many of CC's Lua APIs, and a couple of the Java ones, through the use of stubs. We then export these to HTML using illuaminate [1] and upload them to our documentation site [2]. Uploads currently occur on pushes to master and any release/tag. The site is entirely static - there is no way to switch between versions, etc... but hopefully we can improve this in the future. [1]: github.com/SquidDev/illuaminate/ [2]: https://tweaked.cc/
2020-04-10 09:27:53 +00:00
(index doc/index.md)
Update illuaminate again - Generate theme-color. Hopefully this time it works! - Specify a site url. Technically this is wrong (we should use the current git branch), but it's good enough for now. - Move some options into a sub-category.
2020-12-28 18:20:13 +00:00
(site
(title "CC: Tweaked")
(logo src/main/resources/pack.png)
(url https://tweaked.cc/)
(source-link https://github.com/SquidDev-CC/CC-Tweaked/blob/${commit}/${path}#L${line})
(styles src/web/styles.css)
(scripts build/rollup/index.js)
(head doc/head.html))
An initial stab at documentation generation (#360) This adds documentation comments to many of CC's Lua APIs, and a couple of the Java ones, through the use of stubs. We then export these to HTML using illuaminate [1] and upload them to our documentation site [2]. Uploads currently occur on pushes to master and any release/tag. The site is entirely static - there is no way to switch between versions, etc... but hopefully we can improve this in the future. [1]: github.com/SquidDev/illuaminate/ [2]: https://tweaked.cc/
2020-04-10 09:27:53 +00:00
Add documentation for peripherals No clue how we're going to do this for the dynamic peripheral system if/when that ships, but this is a good first stage. Like the Java APIs, this relies on stub files, so we can't link to the implementation which is a bit of a shame. However, it's a good first step.
2020-06-24 11:10:54 +00:00
(module-kinds
Generate docs for generic peripherals This was the easy bit. Now I've got to write them!
2020-12-10 22:16:49 +00:00
(peripheral Peripherals)
Add some initial documentation for events Credit to @BradyFromDiscord for writing these. See #640 and #565. Co-authored-by: Brady <bradyakent@gmail.com
2021-01-14 18:19:22 +00:00
(generic_peripheral "Generic Peripherals")
(event Events))
Add documentation for peripherals No clue how we're going to do this for the dynamic peripheral system if/when that ships, but this is a good first stage. Like the Java APIs, this relies on stub files, so we can't link to the implementation which is a bit of a shame. However, it's a good first step.
2020-06-24 11:10:54 +00:00
An initial stab at documentation generation (#360) This adds documentation comments to many of CC's Lua APIs, and a couple of the Java ones, through the use of stubs. We then export these to HTML using illuaminate [1] and upload them to our documentation site [2]. Uploads currently occur on pushes to master and any release/tag. The site is entirely static - there is no way to switch between versions, etc... but hopefully we can improve this in the future. [1]: github.com/SquidDev/illuaminate/ [2]: https://tweaked.cc/
2020-04-10 09:27:53 +00:00
(library-path
/doc/stub/
Runnable examples (#576) Provides a basic interface for running examples on tweaked.cc. This is probably janky as anything, but it works on my machine. This is the culmination of 18 months of me building far too much infrastructure (copy-cat, illuaminate), so that's nice I guess. I should probably get out more.
2020-11-12 19:01:50 +00:00
/build/docs/luaJavadoc/
An initial stab at documentation generation (#360) This adds documentation comments to many of CC's Lua APIs, and a couple of the Java ones, through the use of stubs. We then export these to HTML using illuaminate [1] and upload them to our documentation site [2]. Uploads currently occur on pushes to master and any release/tag. The site is entirely static - there is no way to switch between versions, etc... but hopefully we can improve this in the future. [1]: github.com/SquidDev/illuaminate/ [2]: https://tweaked.cc/
2020-04-10 09:27:53 +00:00
Update illuaminate - Fix doc library-path - Only style <pre> code blocks as executable. Skip <code> ones. - Document the default parameters in gps. Yes, we should do it everywhere, but one has to start somewhere!
2021-01-06 17:42:13 +00:00
/src/main/resources/*/computercraft/lua/rom/apis/
/src/main/resources/*/computercraft/lua/rom/apis/command/
/src/main/resources/*/computercraft/lua/rom/apis/turtle/
An initial stab at documentation generation (#360) This adds documentation comments to many of CC's Lua APIs, and a couple of the Java ones, through the use of stubs. We then export these to HTML using illuaminate [1] and upload them to our documentation site [2]. Uploads currently occur on pushes to master and any release/tag. The site is entirely static - there is no way to switch between versions, etc... but hopefully we can improve this in the future. [1]: github.com/SquidDev/illuaminate/ [2]: https://tweaked.cc/
2020-04-10 09:27:53 +00:00
Update illuaminate - Fix doc library-path - Only style <pre> code blocks as executable. Skip <code> ones. - Document the default parameters in gps. Yes, we should do it everywhere, but one has to start somewhere!
2021-01-06 17:42:13 +00:00
/src/main/resources/*/computercraft/lua/rom/modules/main/
/src/main/resources/*/computercraft/lua/rom/modules/command/
/src/main/resources/*/computercraft/lua/rom/modules/turtle/))
An initial stab at documentation generation (#360) This adds documentation comments to many of CC's Lua APIs, and a couple of the Java ones, through the use of stubs. We then export these to HTML using illuaminate [1] and upload them to our documentation site [2]. Uploads currently occur on pushes to master and any release/tag. The site is entirely static - there is no way to switch between versions, etc... but hopefully we can improve this in the future. [1]: github.com/SquidDev/illuaminate/ [2]: https://tweaked.cc/
2020-04-10 09:27:53 +00:00
Lint bios and the rom (#321) We now use illuaminate[1]'s linting facilities to check the rom and bios.lua for a couple of common bugs and other problems. Right now this doesn't detect any especially important bugs, though it has caught lots of small things (unused variables, some noisy code). In the future, the linter will grow in scope and features, which should allow us to be stricter and catch most issues. As a fun aside, we started off with ~150 bugs, and illuaminate was able to fix all but 30 of them, which is pretty neat. [1]: https://github.com/SquidDev/illuaminate
2019-12-03 23:26:13 +00:00
(at /
(linters
Reformat bracketed expressions in Lua - Parenthesised expressions (function calls, arguments, etc...) should never have spaces in them. - Tables always will have spaces inside.
2020-04-18 09:09:40 +00:00
syntax:string-index
Replace string.len with #
2019-12-10 18:54:43 +00:00
;; It'd be nice to avoid this, but right now there's a lot of instances of
;; it.
Lint bios and the rom (#321) We now use illuaminate[1]'s linting facilities to check the rom and bios.lua for a couple of common bugs and other problems. Right now this doesn't detect any especially important bugs, though it has caught lots of small things (unused variables, some noisy code). In the future, the linter will grow in scope and features, which should allow us to be stricter and catch most issues. As a fun aside, we started off with ~150 bugs, and illuaminate was able to fix all but 30 of them, which is pretty neat. [1]: https://github.com/SquidDev/illuaminate
2019-12-03 23:26:13 +00:00
-var:set-loop
;; It's useful to name arguments for documentation, so we allow this. It'd
;; be good to find a compromise in the future, but this works for now.
Fix usages of global variables - Lint references to unknown fields of modules, excluding the keys and colours modules. This caught several silly errors in our stub files, but nothing else. - Lint on using unknown globals. This highlighted a couple of really silly mistakes. Fixes #427. - Add documentation for fs.attributes, fs.getCapacity and pocket, as they were not defined before. Co-authored-by: JackMacWindows <jackmacwindowslinux@gmail.com>
2020-04-28 08:42:34 +00:00
-var:unused-arg)
Update illuaminate config
2020-02-04 16:41:29 +00:00
Reformat bracketed expressions in Lua - Parenthesised expressions (function calls, arguments, etc...) should never have spaces in them. - Tables always will have spaces inside.
2020-04-18 09:09:40 +00:00
(lint
(bracket-spaces
(call no-space)
(function-args no-space)
(parens no-space)
(table space)
Fix usages of global variables - Lint references to unknown fields of modules, excluding the keys and colours modules. This caught several silly errors in our stub files, but nothing else. - Lint on using unknown globals. This highlighted a couple of really silly mistakes. Fixes #427. - Add documentation for fs.attributes, fs.getCapacity and pocket, as they were not defined before. Co-authored-by: JackMacWindows <jackmacwindowslinux@gmail.com>
2020-04-28 08:42:34 +00:00
(index no-space))
;; colours imports from colors, and we don't handle that right now.
;; keys is entirely dynamic, so we skip it.
Document remaining OS functions (#554)
2020-10-11 21:38:18 +00:00
(dynamic-modules colours keys _G)
Fix usages of global variables - Lint references to unknown fields of modules, excluding the keys and colours modules. This caught several silly errors in our stub files, but nothing else. - Lint on using unknown globals. This highlighted a couple of really silly mistakes. Fixes #427. - Add documentation for fs.attributes, fs.getCapacity and pocket, as they were not defined before. Co-authored-by: JackMacWindows <jackmacwindowslinux@gmail.com>
2020-04-28 08:42:34 +00:00
(globals
:max
_CC_DEFAULT_SETTINGS
_CC_DISABLE_LUA51_FEATURES
;; Ideally we'd pick these up from bios.lua, but illuaminate currently
;; isn't smart enough.
sleep write printError read rs)))
Lint bios and the rom (#321) We now use illuaminate[1]'s linting facilities to check the rom and bios.lua for a couple of common bugs and other problems. Right now this doesn't detect any especially important bugs, though it has caught lots of small things (unused variables, some noisy code). In the future, the linter will grow in scope and features, which should allow us to be stricter and catch most issues. As a fun aside, we started off with ~150 bugs, and illuaminate was able to fix all but 30 of them, which is pretty neat. [1]: https://github.com/SquidDev/illuaminate
2019-12-03 23:26:13 +00:00
Replace string.len with #
2019-12-10 18:54:43 +00:00
;; We disable the unused global linter in bios.lua and the APIs. In the future
Lint bios and the rom (#321) We now use illuaminate[1]'s linting facilities to check the rom and bios.lua for a couple of common bugs and other problems. Right now this doesn't detect any especially important bugs, though it has caught lots of small things (unused variables, some noisy code). In the future, the linter will grow in scope and features, which should allow us to be stricter and catch most issues. As a fun aside, we started off with ~150 bugs, and illuaminate was able to fix all but 30 of them, which is pretty neat. [1]: https://github.com/SquidDev/illuaminate
2019-12-03 23:26:13 +00:00
;; hopefully we'll get illuaminate to handle this.
(at
Add documentation for shell and multishell Heh, one place we're more complete than cc.cc :p.
2020-04-22 13:39:39 +00:00
(/src/main/resources/*/computercraft/lua/bios.lua
/src/main/resources/*/computercraft/lua/rom/apis/)
Replace string.len with #
2019-12-10 18:54:43 +00:00
(linters -var:unused-global)
An initial stab at documentation generation (#360) This adds documentation comments to many of CC's Lua APIs, and a couple of the Java ones, through the use of stubs. We then export these to HTML using illuaminate [1] and upload them to our documentation site [2]. Uploads currently occur on pushes to master and any release/tag. The site is entirely static - there is no way to switch between versions, etc... but hopefully we can improve this in the future. [1]: github.com/SquidDev/illuaminate/ [2]: https://tweaked.cc/
2020-04-10 09:27:53 +00:00
(lint (allow-toplevel-global true)))
;; Silence some variable warnings in documentation stubs.
Runnable examples (#576) Provides a basic interface for running examples on tweaked.cc. This is probably janky as anything, but it works on my machine. This is the culmination of 18 months of me building far too much infrastructure (copy-cat, illuaminate), so that's nice I guess. I should probably get out more.
2020-11-12 19:01:50 +00:00
(at (/doc/stub/ /build/docs/luaJavadoc/)
An initial stab at documentation generation (#360) This adds documentation comments to many of CC's Lua APIs, and a couple of the Java ones, through the use of stubs. We then export these to HTML using illuaminate [1] and upload them to our documentation site [2]. Uploads currently occur on pushes to master and any release/tag. The site is entirely static - there is no way to switch between versions, etc... but hopefully we can improve this in the future. [1]: github.com/SquidDev/illuaminate/ [2]: https://tweaked.cc/
2020-04-10 09:27:53 +00:00
(linters -var:unused-global)
(lint (allow-toplevel-global true)))
Some tiny bits of documentation cleanup I'm really good at this English lark :D:.
2020-04-21 11:12:44 +00:00
Add documentation for shell and multishell Heh, one place we're more complete than cc.cc :p.
2020-04-22 13:39:39 +00:00
;; Suppress warnings for currently undocumented modules.
Some tiny bits of documentation cleanup I'm really good at this English lark :D:.
2020-04-21 11:12:44 +00:00
(at
Add documentation for peripherals No clue how we're going to do this for the dynamic peripheral system if/when that ships, but this is a good first stage. Like the Java APIs, this relies on stub files, so we can't link to the implementation which is a bit of a shame. However, it's a good first step.
2020-06-24 11:10:54 +00:00
(; Java APIs
Add documentation for shell and multishell Heh, one place we're more complete than cc.cc :p.
2020-04-22 13:39:39 +00:00
/doc/stub/http.lua
/doc/stub/os.lua
/doc/stub/turtle.lua
Document remaining OS functions (#554)
2020-10-11 21:38:18 +00:00
/doc/stub/global.lua
Generate documentation stubs from Javadocs illuaminate does not handle Java files, for obvious reasons. In order to get around that, we have a series of stub files within /doc/stub which mirrored the Java ones. While this works, it has a few problems: - The link to source code does not work - it just links to the stub file. - There's no guarantee that documentation remains consistent with the Java code. This change found several methods which were incorrectly documented beforehand. We now replace this with a custom Java doclet[1], which extracts doc comments from @LuaFunction annotated methods and generates stub-files from them. These also contain a @source annotation, which allows us to correctly link them back to the original Java code. There's some issues with this which have yet to be fixed. However, I don't think any of them are major blockers right now: - The custom doclet relies on Java 9 - I think it's /technically/ possible to do this on Java 8, but the API is significantly uglier. This means that we need to run javadoc on a separate JVM. This is possible, and it works locally and on CI, but is definitely not a nice approach. - illuaminate now requires the doc stubs to be generated in order for the linter to pass, which does make running the linter locally much harder (especially given the above bullet point). We could notionally include the generated stubs (or at least a cut down version of them) in the repo, but I'm not 100% sure about that. [1]: https://docs.oracle.com/javase/9/docs/api/jdk/javadoc/doclet/package-summary.html
2020-07-03 12:31:26 +00:00
; Java generated APIs
Runnable examples (#576) Provides a basic interface for running examples on tweaked.cc. This is probably janky as anything, but it works on my machine. This is the culmination of 18 months of me building far too much infrastructure (copy-cat, illuaminate), so that's nice I guess. I should probably get out more.
2020-11-12 19:01:50 +00:00
/build/docs/luaJavadoc/turtle.lua
Add documentation for peripherals No clue how we're going to do this for the dynamic peripheral system if/when that ships, but this is a good first stage. Like the Java APIs, this relies on stub files, so we can't link to the implementation which is a bit of a shame. However, it's a good first step.
2020-06-24 11:10:54 +00:00
; Peripherals
Runnable examples (#576) Provides a basic interface for running examples on tweaked.cc. This is probably janky as anything, but it works on my machine. This is the culmination of 18 months of me building far too much infrastructure (copy-cat, illuaminate), so that's nice I guess. I should probably get out more.
2020-11-12 19:01:50 +00:00
/build/docs/luaJavadoc/drive.lua
/build/docs/luaJavadoc/speaker.lua
/build/docs/luaJavadoc/printer.lua
Generate docs for generic peripherals This was the easy bit. Now I've got to write them!
2020-12-10 22:16:49 +00:00
; Generic peripherals
/build/docs/luaJavadoc/fluid_storage.lua
Add documentation for peripherals No clue how we're going to do this for the dynamic peripheral system if/when that ships, but this is a good first stage. Like the Java APIs, this relies on stub files, so we can't link to the implementation which is a bit of a shame. However, it's a good first step.
2020-06-24 11:10:54 +00:00
; Lua APIs
Add documentation for shell and multishell Heh, one place we're more complete than cc.cc :p.
2020-04-22 13:39:39 +00:00
/src/main/resources/*/computercraft/lua/rom/apis/io.lua
Document and test the redstone library The tests may be a little agressive, but I wanted some sanity checks for the 1.15 API rewrite.
2020-05-15 09:03:47 +00:00
/src/main/resources/*/computercraft/lua/rom/apis/window.lua)
Add documentation for shell and multishell Heh, one place we're more complete than cc.cc :p.
2020-04-22 13:39:39 +00:00
Generate documentation stubs from Javadocs illuaminate does not handle Java files, for obvious reasons. In order to get around that, we have a series of stub files within /doc/stub which mirrored the Java ones. While this works, it has a few problems: - The link to source code does not work - it just links to the stub file. - There's no guarantee that documentation remains consistent with the Java code. This change found several methods which were incorrectly documented beforehand. We now replace this with a custom Java doclet[1], which extracts doc comments from @LuaFunction annotated methods and generates stub-files from them. These also contain a @source annotation, which allows us to correctly link them back to the original Java code. There's some issues with this which have yet to be fixed. However, I don't think any of them are major blockers right now: - The custom doclet relies on Java 9 - I think it's /technically/ possible to do this on Java 8, but the API is significantly uglier. This means that we need to run javadoc on a separate JVM. This is possible, and it works locally and on CI, but is definitely not a nice approach. - illuaminate now requires the doc stubs to be generated in order for the linter to pass, which does make running the linter locally much harder (especially given the above bullet point). We could notionally include the generated stubs (or at least a cut down version of them) in the repo, but I'm not 100% sure about that. [1]: https://docs.oracle.com/javase/9/docs/api/jdk/javadoc/doclet/package-summary.html
2020-07-03 12:31:26 +00:00
(linters -doc:undocumented -doc:undocumented-arg -doc:undocumented-return))
Add documentation for shell and multishell Heh, one place we're more complete than cc.cc :p.
2020-04-22 13:39:39 +00:00
Document remaining OS functions (#554)
2020-10-11 21:38:18 +00:00
;; Suppress warnings for the BIOS using its own deprecated members for now.
(at /src/main/resources/*/computercraft/lua/bios.lua
(linters -var:deprecated))
Fix usages of global variables - Lint references to unknown fields of modules, excluding the keys and colours modules. This caught several silly errors in our stub files, but nothing else. - Lint on using unknown globals. This highlighted a couple of really silly mistakes. Fixes #427. - Add documentation for fs.attributes, fs.getCapacity and pocket, as they were not defined before. Co-authored-by: JackMacWindows <jackmacwindowslinux@gmail.com>
2020-04-28 08:42:34 +00:00
(at /src/test/resources/test-rom
Properly deprecate colors.rgb8
2020-08-04 18:50:36 +00:00
; We should still be able to test deprecated members.
(linters -var:deprecated)
Fix usages of global variables - Lint references to unknown fields of modules, excluding the keys and colours modules. This caught several silly errors in our stub files, but nothing else. - Lint on using unknown globals. This highlighted a couple of really silly mistakes. Fixes #427. - Add documentation for fs.attributes, fs.getCapacity and pocket, as they were not defined before. Co-authored-by: JackMacWindows <jackmacwindowslinux@gmail.com>
2020-04-28 08:42:34 +00:00
(lint
(globals
:max sleep write
cct_test describe expect howlci fail it pending stub)))
Runnable examples (#576) Provides a basic interface for running examples on tweaked.cc. This is probably janky as anything, but it works on my machine. This is the culmination of 18 months of me building far too much infrastructure (copy-cat, illuaminate), so that's nice I guess. I should probably get out more.
2020-11-12 19:01:50 +00:00
(at /src/web/mount/expr_template.lua (lint (globals :max __expr__)))
Reference in New Issue Copy Permalink