This way their name doesn't get mangle by the broken magic. It will also
eventually allow to `error()` in the template when the implicit
`@function` is used.
This commit also fixes a large number of issues found while
proof-reading everything.
ldoc has a magical `@classmod` module type which tries to detect
what is a method and what is a static function. It fails about as
often as it works. This commit makes everything explicit to remove
such issues.
Fixes#2640
Ref #1373
The module names for also have their alias. The commit also remove 2
deprecated module that were forgotton in the previous "get rid of the
deprecated modules in the doc" PR.
It worked fine for the table in the header, but the name is also used in
the "main" documentation below. This caused the while text to be within
the "<a>" section.
It was displayed for most sections, but not the functions. This is
problem when the doc already contains a bullet list just before the
parameter section. The two looked as if they were a single list.
There was some issues like `gears.shape.circle` being called
`module.circle`.
There is also a disparity between how the constructor and "normal"
functions are called.
This commit attempts to force everything to have the full module name.
Previously, there was some `module:foo()` or `gears.object:foo()`
because the doc used the "raw" name and/or, in some undefined and
race condition prone (due to `pairs()` order), the formatted
"classmod" name.
Now, just display `:foo()` and be done with it.
This library allows to get a human-readable string describing X11
requests, events, and errors. We now use this library to pretty-print
X11 errors if we get any.
To test this code, I added the following two lines to AwesomeWM so that
X11 errors are generated:
xcb_set_input_focus(globalconf.connection, 42, 42, 42);
xcb_randr_set_output_primary(globalconf.connection,
globalconf.screen->root, 42);
Output without xcb-errors:
X error: request=SetInputFocus (major 42, minor 0), error=BadValue (2)
X error: request=(null) (major 140, minor 30), error=(null) (147)
Output with xcb-errors:
X error: request=SetInputFocus (major 42, minor 0), error=Value (2)
X error: request=RandR-SetOutputPrimary (major 140, minor 30), error=RandR-BadOutput (147)
Signed-off-by: Uli Schlachter <psychon@znc.in>
The commit also re-work the build target so if the file are deleted,
then they are created again. Using `file(COPY ...)` and
`file(MAKE_DIRECTORY ...)` as done previously caused some file to be out
of date or not being regenerated at all.
This commit also fixes some broken target that depended on `file(` and
`configure_file` CMake command not being part of any target.
Fix#2342
Until now there wasn't much documentation available about how to use
these properties. With the new work on `awful.spawn` that rely more and
more on `awful.rules` integration, it is worth fixing.
This commit add a new documentation section and a future commit will
aggregate them to generate an index.
Adds a badge showing the number of people helping this repo on CodeTriage.
[](https://www.codetriage.com/awesomewm/awesome)
## What is CodeTriage?
CodeTriage is an Open Source app that is designed to make contributing to Open Source projects easier. It works by sending subscribers a few open issues in their inbox. If subscribers get busy, there is an algorithm that backs off issue load so they do not get overwhelmed
[Read more about the CodeTriage project](https://www.codetriage.com/what).
## Why am I getting this PR?
Your project was picked by the human, @schneems. They selected it from the projects submitted to https://www.codetriage.com and hand edited the PR. How did your project get added to [CodeTriage](https://www.codetriage.com/what)? Roughly over 1 year ago, [cameronjacobson](https://github.com/cameronjacobson) added this project to CodeTriage in order to start contributing. Since then, 8 people have subscribed to help this repo.
## What does adding a badge accomplish?
Adding a badge invites people to help contribute to your project. It also lets developers know that others are invested in the longterm success and maintainability of the project.
You can see an example of a CodeTriage badge on these popular OSS READMEs:
- [](https://www.codetriage.com/rails/rails) https://github.com/rails/rails
- [](https://www.codetriage.com/crystal-lang/crystal) https://github.com/crystal-lang/crystal
## Have a question or comment?
While I am a bot, this PR was manually reviewed and monitored by a human - @schneems. My job is writing commit messages and handling PR logistics.
If you have any questions, you can reply back to this PR and they will be answered by @schneems. If you do not want a badge right now, no worries, close the PR, you will not hear from me again.
Thanks for making your project Open Source! Any feedback is greatly appreciated.
Before this commit, there was a conflict between the spawn and
awful.rules rules.
Also, modules such as Tryannical monkey-patched this function to
add their own rules to the mix. This commit introduce a proper
API to add handlers.
The order is crutial for this to work, so a dependency system is
also added.
Fix#1482
Do it now since the future awful.popup and notification widget
also uses it.
The `load_ldoc.cmake` changes allow to include `.ldoc` blocks in
existing ldoc comments. Previously, it added some extra newlines
and an autogenerated comments saying the content below was imported.
The problem is that this prevented the system to be used for shared
function arguments.
This commit also renames the `wibar` argument table from `arg` to
`args` as the name has to be the same in the `wibox` and `wibar`
constructor for this to work.
This new paragraph might not be great and it certainly is less
informative than what the wiki said here (it suggested to use some
library for widgets and explained how to use it). However, this new
paragraph is definitely better than the todo that was here for far too
long.
Signed-off-by: Uli Schlachter <psychon@znc.in>
Previously this code checked the generated documentation to decide if
something is a class or a module. Now, it parses the source file and
looks for the @classmod, @module and @submodule tags to make the same
decision.
Fixes: https://github.com/awesomeWM/awesome/issues/1255
Signed-off-by: Uli Schlachter <psychon@znc.in>
These are supposed to eventually replace the already-existing functions
in gears.surface which have a similar signature
Signed-off-by: Uli Schlachter <psychon@znc.in>
luaL_dostring(L, s) is a macro that expands to
luaL_loadstring(L,s)||lua_pcall(L,0,LUA_MULTRET,0). Then,
lua_pcall(L,n,r,f) sometimes (since Lua 5.3?) is a macro that expands to
lua_pcallk(L,n,r,f,0,NULL), but can sometimes also just be a function.
Explaining all the above would make this section more complicated and
apparently no one uses this hint anyway, because no one told us yet that
this hint does not work.
Signed-off-by: Uli Schlachter <psychon@znc.in>
In awesome 3.5, the default themes set a global variable called "theme".
This was, I think, not intentional and we changed this when luacheck
found this issue. However, the "my first awesome" document from the old
wiki made use of this fact and so many people were using this hack. This
commit fixes our copy of "my first awesome".
Signed-off-by: Uli Schlachter <psychon@znc.in>
This is a follow-up to 052cda939b. Expressions like 's.index == 2'
and 's == screen.primary' might work at first. However, they are not
"dynamic": If screens are added/removed or the primary screen changes,
then the widgets are not updated to follow this.
Instead, the example now uses the new awful.widget.only_on_screen
container which provides the needed dynamic behaviour.
This is arguably "the real fix" to #1562 and #1565.
Signed-off-by: Uli Schlachter <psychon@znc.in>
ldoc formatting has problems with code block lines that start with
spaces. use non-blocking-space (unicode 0xa0) as a work around.
Signed-off-by: Justin Charette <charetjc@gmail.com>
- added note that `awesome.quit` must be wrapped in an anonymous
function when used as a menu command.
- corrected tasklist diff to include missing lines from rc.lua. the
porting guide code doesn't make much sense otherwise.
- cleaned up diff columns on a couple other code blocks.
Signed-off-by: Justin Charette <charetjc@gmail.com>
Some `+` and `-` were missing because it re-indented the content
based on the first code line. It then truncated whatever was
below.
Pushing this to master because Ubuntu/Z, Debian/Sid and Arch just
upgraded to 4.0 and angry reports are coming in *fast*.
io.open returns nil, an error message and an error code on failure. This
perfectly fits assert which will make the script fail with the error
message. Previously it would fail with "attempted to index a nil value".
Reference: https://www.reddit.com/r/awesomewm/comments/5kyqji/cant_build_git_awesome/
Signed-off-by: Uli Schlachter <psychon@znc.in>
This adds a short text with some hopefully helpful pointers to the top
of the index.html generated by ldoc.
Signed-off-by: Uli Schlachter <psychon@znc.in>
This document is based on the "my first awesome"-page in the old wiki.
Large parts of it are taken almost verbatim from it while others were
handled more freely. For example, instead of referring to the man page
for an overview of the available key bindings, this now mentions Mod4+S.
The "Add widgets"-section is just a todo. The wiki page refers to
Vicious which does not really work for our api documentation. However, I
also didn't want to just drop this part.
Signed-off-by: Uli Schlachter <psychon@znc.in>
I am no longer sure why I added this file. It doesn't really belong into
the awesome source code. It is better suited to be added to our web
page, I think.
Signed-off-by: Uli Schlachter <psychon@znc.in>
Cleanup and point to the GitHub page for the recent contributors.
Some older contributors don't have GitHub accounts, so are
invisible, so I left the old list intact.
This commit doesn't add any useful documentation, but adds
previously hidden documentation variables. It can be the basis
of a better layout documentation.
Fix#1246
This function was iterating over a table with pairs() to generate output (the
sample theme file). Since pairs() does not guarantee any iteration order, this
lead to a different order each time this file was generated. This is, for
example, visible in the diffs in the generate api documentation repository.
Fix this by using a self-made iteration function which behaves like pairs(), but
guarantees an iteration order sorted by keys.
Signed-off-by: Uli Schlachter <psychon@znc.in>
It does not provide much value. The version number is already known to
ldoc globally in the "description" variable.
Signed-off-by: Uli Schlachter <psychon@znc.in>
Previously, this mentioned non-existent arguments (widget) and
duplicated parts of the (not yet really existing) API documentation for
find_widgets().
Signed-off-by: Uli Schlachter <psychon@znc.in>
Just because they sound similar to mouse::press and mouse::release does
not mean that the arguments are the same. Perhaps they should be, but
that's another story.
Signed-off-by: Uli Schlachter <psychon@znc.in>
This adds a tparam alias "@screen" for "@tparam screen" (when used to
document e.g. arguments for callbacks), and "@screen_or_idx" when a
function accepts a "screen" or "number".
The default config had tables like mywibox and mywibox[s] was the wibox
that is visible on screen s. When a screen is removed, nothing cleans up
these tables and so the screen and the wibox could not be garbage
collected. The same applies to the layoutbox, taglist etc.
This commit removes the global mywibox table and instead saves it as a
property on the screen. This way, the screen is not explicitly
referenced and when it is removed, the screen, its wibox and all of its
widgets become unreachable and can be garbage collected.
This commit also updates the docs and the tests that referenced things
(mostly the wibox) via mywibox[s] to now use s.mywibox.
Fixes: https://github.com/awesomeWM/awesome/issues/1125
Signed-off-by: Uli Schlachter <psychon@znc.in>
This meta-lua script takes the "raw" awesomerc.lua and turn it
into the final file and generate a documentation page from its
parsed content. It support
* Turn {{{ into markdown categories
* Turn top level comments into documentation
* Add custom documentation sections
* Parse the code to add links for each API calls
This helps generate a good entry point for new users wanting to
understand the content of rc.lua without searching the API by
hand.
Over time, this will also become the basis of the documentation.
If `rc.lua` is separated into several files, this will be easy to fix
this script. It could even do the separation itself from a monolitic
file using the already implemented {{{ parser.
This uses the new support introduced in f0f31bc305 in the docs and in
tests/run.sh, removing an useless use of cat/echo.
Signed-off-by: Uli Schlachter <psychon@znc.in>
The requirement to call add_signal() was added to catch typos. However, this
requirement became increasingly annoying with property::<name> signals and e.g.
gears.object allowing arbitrary properties to be changed.
All of this ended up in a single commit because tests/examples fails if I first
let add_signal() emit a deprecation warning.
Signed-off-by: Uli Schlachter <psychon@znc.in>
This system allow containers, widgets and layouts to be listed in
the documentation with an example screenshot.
It uses raw HTML due to ldoc limitations, but as it is autogenerated,
it wont be user visible.
This was only partly converted to markdown. It still refers to wiki pages with
wiki syntax, because we first have to decide on what happens with the wiki
before this can be updated.
Signed-off-by: Uli Schlachter <psychon@znc.in>
This is the current version of the FAQ in the wiki converted to markdown, but
some IMO bogus content was stripped (e.g. references to awesome being a
non-reparenting WM).
Signed-off-by: Uli Schlachter <psychon@znc.in>
ldoc doesn't allow to specify fields from class "A" into class "B",
so the only solution is to merge the 2.
Also, one of the most common complain on IRC since Awesome 3.0 is
that the client API doc is confusing since it is in 2 different files.
Also restore the `awful.client` doc link, point to `client`
This will avoid broken links.
Previously, the `Signals` section was shown before the `Functions`.
This was confusing and different from other framework documentation.
It partially work. Not all ldoc output display the functions at the
top, but some does. Previously, none did.
This commit also add 3 new sections:
* property: For object properties, replacing the "fields" table
from the current documentations.
* deprecated: For deprecated methods
* beautiful: For widgets theme options
Emmanuel Lepage Vallee
Uli Schlachter
Uli Schlachter
Daniel Hahler
actionless
mergify[bot]
Sergey Vlasov
Daniel Hahler
Joseph Herlant
README Bot
Reiner Herrmann
Luke Bonham
Nick Diego Yamane
Åsmund Ervik
getzze
Kevin Zander
Jonathan McCrohan
Sudo Nice
Justin Charette
Holger Schurig
Mikko Valkonen
Enric Morales
Uli Schlachter
