diff --git a/.gitignore b/.gitignore index 4e1d905174..2f3d27c419 100644 --- a/.gitignore +++ b/.gitignore @@ -15,7 +15,6 @@ modules/luci-base/src/lib/plural_formula.h modules/luci-compat/src/contrib/lemon modules/luci-compat/src/plural_formula.c modules/luci-compat/src/plural_formula.h -docs/jsapi/* -!docs/jsapi/README.md +docs/**/*.* **eslint.config** !eslint.config.mjs diff --git a/README.md b/README.md index 7a9027f834..10c3a7f766 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ src-git luci https://github.com/openwrt/luci.git ``` To install all its package definitions, run: -``` +```sh ./scripts/feeds update luci ./scripts/feeds install -a -p luci ``` @@ -23,7 +23,8 @@ To install all its package definitions, run: You can browse the generated API documentation directly on Github. - - [Server side Lua APIs](http://openwrt.github.io/luci/api/index.html); Note: deprecated - Lua will be removed in future. Use ucode rpcd for server side operations. +Use [ucode](https://ucode.mein.io/) and rpcd for server side operations. + - [Client side JavaScript APIs](http://openwrt.github.io/luci/jsapi/index.html) ## Development diff --git a/docs/LMO.md b/doc_gen/LMO.md similarity index 100% rename from docs/LMO.md rename to doc_gen/LMO.md diff --git a/doc_gen/README.md b/doc_gen/README.md new file mode 100644 index 0000000000..4dd22db20a --- /dev/null +++ b/doc_gen/README.md @@ -0,0 +1,10 @@ +# LuCI Documentation + +Start with the [LuCI Client side JavaScript APIs](LuCI.html) + + + + +## Historical + +The older [Lua API docs](api/index.html) are available for historical reference. \ No newline at end of file diff --git a/doc_gen/extra.css b/doc_gen/extra.css new file mode 100644 index 0000000000..eed3dd1079 --- /dev/null +++ b/doc_gen/extra.css @@ -0,0 +1,35 @@ +.navbar-item.github-home a { + background-image: url("data:image/svg+xml,%3Csvg width='98' height='96' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill-rule='evenodd' clip-rule='evenodd' d='M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z' fill='%2324292f'/%3E%3C/svg%3E"); + background-repeat: no-repeat; + background-size: 1.5em; + background-position: 1rem center; + padding-left: 3rem; +} + +.signature-attributes { + font-style:italic; + font-weight:lighter; + font-variant:sub; +} + +span.param-type { + color:#00918e; +} + +.type-signature { + display: inline-block; + color:#00918e; +} + +.type-signature::after { + content: ' '; +} + +span.signature::after { + content: ' '; +} + +table.props tbody td, +table.params tbody td { + padding: 0.5rem; +} diff --git a/doc_gen/tutorials/JsonRpcHowTo.md b/doc_gen/tutorials/JsonRpcHowTo.md new file mode 100644 index 0000000000..f4eccb8a40 --- /dev/null +++ b/doc_gen/tutorials/JsonRpcHowTo.md @@ -0,0 +1,77 @@ +# Using the JSON-RPC API + +LuCI provides some of its libraries to external applications through a [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) API. +This Howto shows how to use it and provides information about available functions. + +See also +* wiki [rpcd](https://openwrt.org/docs/techref/rpcd) +* wiki [ubus](https://openwrt.org/docs/techref/ubus) + +## Basics +The API is installed by default. + +LuCI comes with an efficient JSON De-/Encoder together with a JSON-RPC-Server which implements the JSON-RPC 1.0 and 2.0 (partly) specifications. +The LuCI JSON-RPC server offers several independent APIs. +Therefore you have to use **different URLs for every exported library**. +Assuming your LuCI-Installation can be reached through `/cgi-bin/luci`, any exported library can be reached via `/cgi-bin/luci/rpc/LIBRARY`. + + +## Authentication +Most exported libraries will require a valid authentication to be called with. +If you get an `HTTP 403 Forbidden` status code you are probably missing a valid authentication token. +To get such a token you have to call the `login` method of the RPC-Library `auth`. +Following our example from above this login function would be provided at `/cgi-bin/luci/rpc/auth`. +The function accepts 2 parameters: `username` and `password` (of a valid user account on the host system) and returns an authentication token. + +Example: +```sh +curl http:///cgi-bin/luci/rpc/auth --data ' +{ + "id": 1, + "method": "login", + "params": [ + "youruser", + "somepassword" + ] +}' +``` + +response: +```json +{"id":1,"result":"65e60c5a93b2f2c05e61681bf5e94b49","error":null} +``` + +If you want to call any exported library which requires an authentication token you have to append it as a URL parameter auth to the RPC-Server URL. +E.g. instead of calling `/cgi-bin/luci/rpc/LIBRARY` you should call `/cgi-bin/luci/rpc/LIBRARY?auth=TOKEN`. + +If your JSON-RPC client is Cookie-aware (like most browsers are) you will receive the authentication token also with a session cookie and probably don't have to append it to the RPC-Server URL. + + +## Exported Libraries +### uci +The UCI-Library `/rpc/uci` offers functionality to interact with the Universal Configuration Interface. + +**Exported Functions:** + +See [LuCI API](LuCI.uci.html) + +Example: +```sh +curl http:///cgi-bin/luci/rpc/uci?auth=yourtoken --data ' +{ + "method": "get_all", + "params": [ "network" ] +}' +``` + +### fs +The Filesystem library `/rpc/fs` offers functionality to interact with the filesystem on the host machine. + +**Exported Functions:** + +See [fs API](LuCI.fs.html) + + +**Note:** All functions are exported as they are except for `readfile` which encodes its return value in [Base64](https://en.wikipedia.org/wiki/Base64) and `writefile` which only accepts Base64 encoded data as second argument. + + diff --git a/docs/Modules.md b/doc_gen/tutorials/Modules.md similarity index 75% rename from docs/Modules.md rename to doc_gen/tutorials/Modules.md index 0c9852954e..44baa7adc9 100644 --- a/docs/Modules.md +++ b/doc_gen/tutorials/Modules.md @@ -1,6 +1,4 @@ -# Reference: LuCI Modules - -See [online wiki](https://github.com/openwrt/luci/wiki/Modules) for latest version. +# Authoring LuCI Modules ## Categories @@ -12,13 +10,14 @@ The LuCI modules are divided into several category directories, namely: * protocols - network related plugins * themes - Frontend themes -Each module goes into a subdirectory of this category-directories. +Each module goes into a subdirectory of its respective category-directories. ## Module directory The contents of a module directory are as follows: ### Makefile -This is the module's makefile. If the module just contains Lua sourcecode or resources then the following Makefile should suffice. +This is the module's makefile. If the module just contains JS sourcecode or resources then the following Makefile should suffice. + ```Makefile include $(TOPDIR)/rules.mk @@ -29,22 +28,17 @@ include ../../luci.mk # call BuildPackage - OpenWrt buildroot signature ``` - + If you have C(++) code in your module you should include a `src/` subdirectory containing another Makefile supporting a `clean`, a `compile` and an `install` target. The `install` target should deploy its files relative to the predefined `$(DESTDIR)` variable, e.g. -``` + +```sh mkdir -p $(DESTDIR)/usr/bin; cp myexecutable $(DESTDIR)/usr/bin/myexecutable ``` ### src The `src` directory is reserved for C sourcecode. -### luasrc -`luasrc` contains all Lua sourcecode files. These will automatically be stripped or compiled depending on the Make target and are installed in the LuCI installation directory. - -### lua -`lua` is equivalent to `luasrc` but containing Lua files will be installed in the Lua document root. - ### htdocs All files under `htdocs` will be copied to the document root of the target webserver. @@ -61,7 +55,7 @@ See IPKG documentation for details. ## OpenWRT feed integration -If you want to add your module to the LuCI OpenWRT feed you have to add several sections to the `contrib/package/luci/Makefile`. +If you want to add your module to the LuCI OpenWRT feed, you have to add several sections to the `contrib/package/luci/Makefile`. For a Web UI applications this is: diff --git a/docs/ThemesHowTo.md b/doc_gen/tutorials/ThemesHowTo.md similarity index 66% rename from docs/ThemesHowTo.md rename to doc_gen/tutorials/ThemesHowTo.md index 33d8426d33..6c4ef04f12 100644 --- a/docs/ThemesHowTo.md +++ b/doc_gen/tutorials/ThemesHowTo.md @@ -1,5 +1,5 @@ -# HowTo: Create Themes -**Note:** You have already read the [Module Reference](./Modules.md) and the [Template Reference](./Templates.md). +# Creating Themes +**Note:** You have already read the [Module Reference](./Modules.md). We assume you want to call your new theme `mytheme`. Replace `mytheme` with your module name every time this is mentioned in this Howto. @@ -18,31 +18,35 @@ include ../../luci.mk ``` Create the following directory structure inside your theme directory. -* ipkg * htdocs * luci-static * `mytheme` -* luasrc - * view - * themes - * `mytheme` + * resources * root * etc - * uci-defaults + * uci-defaults +* ucode + * template + * themes + * `mytheme` ## Designing -Create two LuCI HTML-Templates named `header.htm` and `footer.htm` under `luasrc/view/themes/mytheme`. -The `header.htm` will be included at the beginning of each rendered page and the `footer.htm` at the end. -So your `header.htm` will probably contain a DOCTYPE description, headers, -the menu and layout of the page and the `footer.htm` will close all remaining open tags and may add a footer bar. +Create two LuCI ucode Templates named `header.ut` and `footer.ut` under `ucode/template/themes/mytheme`. +The `header.ut` will be included at the beginning of each rendered page and the `footer.ut` at the end. +So your `header.ut` will probably contain a DOCTYPE description, headers, +the menu and layout of the page and the `footer.ut` will close all remaining open tags and may add a footer bar. But hey that's your choice: you are the designer ;-). -Just make sure your `header.htm` begins with the following lines: +Just make sure your `header.ut` begins with the following lines: ``` -<% -require("luci.http").prepare_content("text/html") --%> +{% + import { getuid, getspnam } from 'luci.core'; + + const boardinfo = ubus.call('system', 'board'); + + http.prepare_content('text/html; charset=UTF-8'); +-%} ``` This ensures your content is sent to the client with the right content type. @@ -50,19 +54,22 @@ Of course you can adapt `text/html` to your needs. Put any stylesheets, Javascripts, images, ... into `htdocs/luci-static/mytheme`. -Refer to this directory in your header and footer templates as: `<%=media%>`. -That means for a stylesheet `htdocs/luci-static/mytheme/cascade.css` you would write: +Refer to this directory in your header and footer templates as: `{{ media }}`. +That means for an icon `htdocs/luci-static/mytheme/logo.svg` you would write: + ```html - + ``` ## Making the theme selectable If you are done with your work there are two last steps to do. To make your theme OpenWrt-capable and selectable on the settings page, create a file `root/etc/uci-defaults/luci-theme-mytheme` with the following contents: + ```sh #!/bin/sh uci batch <<-EOF set luci.themes.MyTheme=/luci-static/mytheme + set luci.main.mediaurlbase=/luci-static/mytheme commit luci EOF exit 0 diff --git a/doc_gen/tutorials/i18n.md b/doc_gen/tutorials/i18n.md new file mode 100644 index 0000000000..26e90c3550 --- /dev/null +++ b/doc_gen/tutorials/i18n.md @@ -0,0 +1,108 @@ +# Internationalisation (i18n) + +## Use translation function + +### Translations in JavaScript + +Wrap translatable strings with `_()` e.g. `_('string to translate')` and the `i18n-scan.pl` and friends will correctly identify these strings for translation. + +If you have multi line strings you can split them with concatenation: +```js +var mystr = _('this string will translate ' + + 'correctly even though it is ' + + 'a multi line string!'); +``` + +You may also use line continuations `\` syntax: + +```js +var mystr = _('this string will translate \ + correctly even though it is \ + a multi line string'); +``` + +Usually if you have multiple sentences you may need to use a line break. Use the `
` HTML tag like so: +```js +var mystr = _('Port number.') + '
' + + _('E.g. 80 for HTTP'); +``` +Use `
` and **not** `
` or `
`. + +If you have a link inside a translation, move its attributes out of a translation key: +```js +var mystr = _('For further information check the wiki') + .format('href="https://openwrt.org/docs/" target="_blank" rel="noreferrer"') +``` +This will generate a full link with HTML `For further information check the wiki`. The `noreferrer` is important so that it is opened in a new tab (`target="_blank"`). + + +### Translations in Lua controller code and Lua CBIs +As hinted at in the Templates doc, the `%:` invokes a `translate()` function. +In most controller contexts, this is already available for you, but if necessary, is available for include in `luci.i18n.translate` + + +## Translation files +Translations are saved in the folder `po/` within each individual LuCI component directory, e.g. `applications/luci-app-acl/po/`. +The template is in `po/templates/.pot`. +The individual language translation files can be found at `po/[lang]/[package].po`. + +In order to use the commands below you need to have the `gettext` utilities (`msgcat`, `msgfmt`, `msgmerge`) installed on your system. +On Debian/Ubuntu, install them with `sudo apt install gettext`. + + +### Initialize po files + +When you add or update an app, run from your `applications/luci-app-acl/` app folder: +```sh +../../build/i18n-add-language.sh +``` +This creates the skeleton .po files for all available languages open for translation for your app. + +Or from the luci repo root: +```sh +./build/i18n-add-language.sh +``` +This creates the skeleton .po files for all existing languages open for translation for all sub-folders. + +### Rebuild po files (for existing languages) +After you make changes to a package, run: + +```sh +./build/i18n-sync.sh applications/[application] +``` + +Example: +```sh +./build/i18n-sync.sh applications/luci-app-acl +``` + +This only updates those language .po files that already exist in `applications/luci-app-acl/po/`. See the previous step to add a new language. + +Note: the directory argument can be omitted to update all po template and po files. + + +Some packages share translation files, in this case you need to scan through all their folders: + +```sh +./build/i18n-scan.pl applications/[package-1] applications/[package-2] applications/[package-n] > [location of shared template]/[application].pot +``` +This is what the `mkbasepot.sh` script does for the `luci-base` module: + +```sh +./build/i18n-scan.pl \ + modules/luci-base modules/luci-compat modules/luci-lua-runtime \ + modules/luci-mod-network modules/luci-mod-status modules/luci-mod-system \ + protocols themes \ +> modules/luci-base/po/templates/base.pot +``` + +*Note:* The translation catalog for the base system covers multiple components. Use the following commands to update it: + +```sh +./build/mkbasepot.sh +./build/i18n-update.pl +``` + +### Finally + +You can change languages in [System /Language and Style](http://192.168.1.1/cgi-bin/luci/admin/system/system) and check the translation. diff --git a/doc_gen/tutorials/tutorials.json b/doc_gen/tutorials/tutorials.json new file mode 100644 index 0000000000..e51b0066d0 --- /dev/null +++ b/doc_gen/tutorials/tutorials.json @@ -0,0 +1,11 @@ +{ + "i18n": { + "title": "Internationalisation - i18n" + }, + "JsonRpcHowTo": { + "title": "Using JSON RPC daemon" + }, + "ThemesHowTo": { + "title": "Making Themes" + } +} diff --git a/docs/JsonRpcHowTo.md b/docs/JsonRpcHowTo.md deleted file mode 100644 index 46aeb05659..0000000000 --- a/docs/JsonRpcHowTo.md +++ /dev/null @@ -1,120 +0,0 @@ -# HowTo: Using the JSON-RPC API - -See [online wiki](https://github.com/openwrt/luci/wiki/JsonRpcHowTo) for latest version. - -LuCI provides some of its libraries to external applications through a [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) API. -This Howto shows how to use it and provides information about available functions. - -See also -* wiki [rpcd](https://openwrt.org/docs/techref/rpcd) -* wiki [ubus](https://openwrt.org/docs/techref/ubus) - -## Basics -To enable the API, install the following package and restart `uhttpd`: - -```bash -opkg install luci-mod-rpc luci-lib-ipkg luci-compat -/etc/init.d/uhttpd restart -``` - -LuCI comes with an efficient JSON De-/Encoder together with a JSON-RPC-Server which implements the JSON-RPC 1.0 and 2.0 (partly) specifications. -The LuCI JSON-RPC server offers several independent APIs. -Therefore you have to use **different URLs for every exported library**. -Assuming your LuCI-Installation can be reached through `/cgi-bin/luci`, any exported library can be reached via `/cgi-bin/luci/rpc/LIBRARY`. - - -## Authentication -Most exported libraries will require a valid authentication to be called with. -If you get an `HTTP 403 Forbidden` status code you are probably missing a valid authentication token. -To get such a token you have to call the `login` method of the RPC-Library `auth`. -Following our example from above this login function would be provided at `/cgi-bin/luci/rpc/auth`. -The function accepts 2 parameters: `username` and `password` (of a valid user account on the host system) and returns an authentication token. - -Example: -```sh -curl http:///cgi-bin/luci/rpc/auth --data ' -{ - "id": 1, - "method": "login", - "params": [ - "youruser", - "somepassword" - ] -}' -``` - -response: -```json -{"id":1,"result":"65e60c5a93b2f2c05e61681bf5e94b49","error":null} -``` - -If you want to call any exported library which requires an authentication token you have to append it as an URL parameter auth to the RPC-Server URL. -E.g. instead of calling `/cgi-bin/luci/rpc/LIBRARY` you should call `/cgi-bin/luci/rpc/LIBRARY?auth=TOKEN`. - -If your JSON-RPC client is Cookie-aware (like most browsers are) you will receive the authentication token also with a session cookie and probably don't have to append it to the RPC-Server URL. - - -## Exported Libraries -### uci -The UCI-Library `/rpc/uci` offers functionality to interact with the Universal Configuration Interface. - -**Exported Functions:** -* [(string) add(config, type)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.add) -* [(integer) apply(config)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.apply) -* [(object) changes([config])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.changes) -* [(boolean) commit(config)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.commit) -* [(boolean) delete(config, section[, option])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.delete) -* [(boolean) delete_all(config[, type])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.delete_all) -* [(array) foreach(config[, type])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.foreach) -* [(mixed) get(config, section[, option])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.get) -* [(object) get_all(config[, section])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.get_all) -* [(mixed) get_state(config, section[, option])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.get) -* [(boolean) revert(config)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.revert) -* [(name) section(config, type, name, values)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.section) -* [(boolean) set(config, section, option, value)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.set) -* [(boolean) tset(config, section, values)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.tset) - -Example: -```sh -curl http:///cgi-bin/luci/rpc/uci?auth=yourtoken --data ' -{ - "method": "get_all", - "params": [ "network" ] -}' -``` - -### fs -The Filesystem library `/rpc/fs` offers functionality to interact with the filesystem on the host machine. - -**Exported Functions:** - -* [Complete luci.fs library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.fs.html) - -**Note:** All functions are exported as they are except for `readfile` which encodes its return value in [Base64](https://en.wikipedia.org/wiki/Base64) and `writefile` which only accepts Base64 encoded data as second argument. -Note that both functions will only be available when the `luasocket` packet is installed on the host system. - -### sys -The System library `/rpc/sys` offers functionality to interact with the operating system on the host machine. - -**Exported Functions:** -* [Complete luci.sys library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.html) -* [Complete luci.sys.group library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.group.html) prefixing the method name with `group.methodname`. -* [Complete luci.sys.net library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.net.html) prefixing the method name with `net.methodname`. -* [Complete luci.sys.process library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.process.html) prefixing the method name with `process.methodname`. -* [Complete luci.sys.user library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.user.html) with prefix `user`. -* [Complete luci.sys.wifi library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.wifi.html) with prefix `wifi`. - -Example: -```sh -curl http:///cgi-bin/luci/rpc/sys?auth=yourtoken --data ' -{ - "method": "net.conntrack" -}' -``` - -### ipkg -The IPKG library `/rpc/ipkg` offers functionality to interact with the package manager (IPKG or OPKG) on the host machine. - -**Exported Functions:** -* [Complete luci.model.ipkg library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.ipkg.html) - diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index eeb5d0ead4..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# LuCI Documentation - -See Wiki [LuCI Technical Reference](https://openwrt.org/docs/techref/luci) - -## API Reference - -- [Client side JavaScript APIs](jsapi/) -- [How to i18n your module](i18n): internationalization via \*.po and \*.pot files -- [How to make LuCI JS Modules](https://github.com/openwrt/luci/tree/master/applications/luci-app-example): see the luci-app-example in the repo -- [How to use the JSON-RPC](JsonRpcHowTo) -- [How to make themes](ThemesHowTo) -- [LuCI Modules Reference](Modules): can be JS based or Lua (deprecated) - -## Deprecated API Reference (older Lua based APIs) - -- [CBI models reference](CBI):CBI models are Lua files describing the structure of an UCI config file and the resulting HTML form to be evaluated by the CBI parser -- [How to make LuCI Lua Modules](ModulesHowTo): No new Lua modules for client side display are accepted, but some server side things are still done in Lua -- [LMO - Lua Machine Objects](LMO): to pack language strings into a more efficient form for Lua -- [Server side Lua APIs](api/index.html) -- [Templates](Templates): template processor which parses HTML-files to Lua functions and allows to store precompiled template files - -## Archived - -- [LuCI-0.10](LuCI-0.10): No longer used, but useful reference if you encounter older LuCI versions. \ No newline at end of file diff --git a/docs/extra.css b/docs/extra.css new file mode 100644 index 0000000000..eed3dd1079 --- /dev/null +++ b/docs/extra.css @@ -0,0 +1,35 @@ +.navbar-item.github-home a { + background-image: url("data:image/svg+xml,%3Csvg width='98' height='96' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill-rule='evenodd' clip-rule='evenodd' d='M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z' fill='%2324292f'/%3E%3C/svg%3E"); + background-repeat: no-repeat; + background-size: 1.5em; + background-position: 1rem center; + padding-left: 3rem; +} + +.signature-attributes { + font-style:italic; + font-weight:lighter; + font-variant:sub; +} + +span.param-type { + color:#00918e; +} + +.type-signature { + display: inline-block; + color:#00918e; +} + +.type-signature::after { + content: ' '; +} + +span.signature::after { + content: ' '; +} + +table.props tbody td, +table.params tbody td { + padding: 0.5rem; +} diff --git a/docs/jsapi/README.md b/docs/jsapi/README.md deleted file mode 100644 index ecd93766ad..0000000000 --- a/docs/jsapi/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# LuCI client side API documentation - -You can browse the JavaScript apis provided by LuCI here. A good starting point -is the central [luci.js class](https://openwrt.github.io/luci/jsapi/LuCI.html). - diff --git a/jsdoc.conf.json b/jsdoc.conf.json index dbf12f67f5..ad7b2bd6d6 100644 --- a/jsdoc.conf.json +++ b/jsdoc.conf.json @@ -1,25 +1,61 @@ { - "tags": { - "allowUnknownTags": true, - "dictionaries": ["jsdoc","closure"] - }, - "source": { - "include": ["modules/luci-base/htdocs/luci-static/resources"], - "includePattern": ".+\\.js(doc|x)?$" - }, - "plugins": [ - "plugins/markdown" - ], - "templates": { - "cleverLinks": true, - "monospaceLinks": true, - "default": { - "outputSourceFiles": true - } - }, - "opts": { - "destination": "docs/jsapi", - "recurse": true, - "readme": "docs/jsapi/README.md" - } + "tags": { + "allowUnknownTags": true, + "dictionaries": ["jsdoc","closure"] + }, + "source": { + "include": ["modules/luci-base/htdocs/luci-static/resources"], + "includePattern": ".+\\.js(doc|x)?$" + }, + "plugins": [ + "plugins/markdown" + ], + "templates": { + "cleverLinks": true, + "monospaceLinks": true, + "default": { + "outputSourceFiles": true + } + }, + "opts": { + "template": "node_modules/clean-jsdoc-theme", + "template_alt": "@alphanull/jsdoc-vision-theme", + "template_old": "jaguarjs-jsdoc", + "destination": "docs/", + "destination_comment": "output directory in the repo", + "recurse": true, + "readme": "doc_gen/README.md", + "readme_comment": "generates the index.html file", + "tutorials": "doc_gen/tutorials", + "tutorials_comment": "tutorials index. See 'sections' below. jaguarjs does not like the tutorials entry", + "theme_opts": { + "default_theme": "fallback-dark", + "favicon": "themes/luci-theme-bootstrap/htdocs/luci-static/bootstrap/logo.svg", + "title": "LuCI Documentation", + "homepageTitle": "LuCI - Reference Documentation", + "displayModuleHeader": false, + "prefixModuleToSidebarItems_experimental": false, + "includeFilesListInHomepage": false, + "include_css": [ + "doc_gen/extra.css" + ], + "menu": [ + { + "title": "GitHub Project Page", + "link": "https://github.com/openwrt/luci", + "class": "github-home" + } + ], + "sections": [ + "Tutorials", + "Modules", + "Classes", + "Externals" + ] + } + }, + "markdown": { + "hardwrap": false, + "idInHeadings": true + } } diff --git a/package.json b/package.json index e4664e08cf..220b126af6 100644 --- a/package.json +++ b/package.json @@ -1,9 +1,12 @@ { "scripts": { - "doc": "LC_ALL=C jsdoc -c jsdoc.conf.json -t node_modules/jaguarjs-jsdoc" + "docjag": "LC_ALL=C jsdoc -c jsdoc.conf.json -t node_modules/jaguarjs-jsdoc", + "doc": "LC_ALL=C jsdoc -c jsdoc.conf.json" }, "devDependencies": { + "@alphanull/jsdoc-vision-theme": "^1.2.2", + "clean-jsdoc-theme": "^4.3.0", "jaguarjs-jsdoc": "^1.1.0", - "jsdoc": "^3.6.7" + "jsdoc": "^4.0.5" } }