* docs: change links to d.py docs to use stable version instead of v1.0.1
* chore(changelog): add towncrier entry
* docs: add |DPY_VERSION| substitution and :dpy_docs: role
* chore(changelog): update towncrier entries to reflect new changes
* Getting started guide
* Remove DigitalOcean referral link
* Fix typos and mispells, thanks to @Flame442
* Remove cogs.red hyperlink until it is finished
* Add towncrier entry
* Add prolog.txt
This is not necessary for this PR but all of the other cog guides rely on this file.
The cog guides are individual branches based on this one, which is why I'm adding this file right now.
* QA changes
* More QA changes
considering -> assuming
red is a girl, not non-binary
### Replacement for pipenv's environment setup
First of all, there's a new Make recipe for all devs and contributors on both Windows and Posix, `make setupenv`, which is kind of a replacement for `pipenv install --dev`. It creates a virtual environment in `.venv` using the inbuilt `venv` module, clearing out any existing virtual environment if needed first. Then it installs all dev dependencies using our new `dev-requirements.txt` file. `CONTRIBUTING.md` has been updated to reflect all of this.
### Dependency version bumping tool
Secondly, I've added a python script, `tools/bumpdeps.py` to help with bumping dependency versions. It has its own Make recipe too, `make bumpdeps`. This script won't work on Windows (yet). It reads the `tools/primary_deps.ini` file, which contains the primary requirements of Red and its extras with loose version specifiers, and outputs all pinned dependencies, in `setup.cfg` format. It's not a foolproof dependency resolver, it's quite simple, but it's bound to help out a lot. It'll try to give warnings if there might be a version conflict, but updating `setup.cfg` with its output and then doing `pip install -r dev-requirements.txt` will allow pip to issue warnings if something is conflicting.
So to add a new dependency, add it to `tools/primary_deps.ini` in the appropriate place, and either use `make bumpdeps` to completely update all dependencies, or simply add it to `setup.cfg` manually with its sub-dependencies, and all versions pinned.
### Sphinx 2.1.2 (docs changes)
The sphinx update brought along the ability to disable type annotations being rendered in function and method signatures, and I have gladly gone and done that. Type annotations should already be specified under the "Parameters" section, and the way sphinx renders them in function signatures makes them much harder to read.
Also, documented classes will now display what classes they inherit from.
Signed-off-by: Toby Harradine <tobyharradine@gmail.com>
This is in anticipation of #2246, although I've written that PR to not break on 3.6, the feature itself is not usable on 3.6. So I think the best way forward is to simply require python 3.7. This also allows devs and cog creators to utilise all of the new features in 3.7, and it also updates the docs so all operating systems will have 3.7 installed.
Signed-off-by: Toby <tobyharradine@gmail.com>
API changes:
- Cogs must now inherit from `commands.Cog` (see #2151 for discussion and more details)
- All functions which are not decorators in the `redbot.core.checks` module are now deprecated in favour of their counterparts in `redbot.core.utils.mod`. This is to make this module more consistent and end the confusing naming convention.
- `redbot.core.checks.check_overrides` function is now gone, overrideable checks can now be created with the `@commands.permissions_check` decorator
- Command, Group, Cog and Context have some new attributes and methods, but they are for internal use so shouldn't concern cog creators (unless they're making a permissions cog!).
- `__permissions_check_before` and `__permissions_check_after` have been replaced: A cog method named `__permissions_hook` will be evaluated as permissions hooks in the same way `__permissions_check_before` previously was. Permissions hooks can also be added/removed/verified through the new `*_permissions_hook()` methods on the bot object, and they will be verified even when permissions is unloaded.
- New utility method `redbot.core.utils.chat_formatting.humanize_list`
- New dependency [`schema`](https://github.com/keleshev/schema)
User-facing changes:
- When a `@bot_has_permissions` check fails, the bot will respond saying what permissions were actually missing.
- All YAML-related `[p]permissions` subcommands now reside under the `[p]permissions acl` sub-group (tbh I still think the whole cog has too many top-level commands)
- The YAML schema for these commands has been changed
- A rule cannot be set as allow and deny at the same time (previously this would just default to allow)
Documentation:
- New documentation for `redbot.core.commands.requires` and `redbot.core.checks` modules
- Renewed documentation for the permissions cog
- `sphinx.ext.doctest` is now enabled
Note: standard discord.py checks will still behave exactly the same way, in fact they are checked before `Requires` is looked at, so they are not overrideable.
Signed-off-by: Toby Harradine <tobyharradine@gmail.com>
* Upgrade sphinx version to 1.7+
* Fix title overlines/underlines in autostart_systemd.rst
* Skip trying to document a method from discord.py
* Add escaped space after backtick
* Escape underscores (sphinx tries to interpret a hyperlink)
* Use fully qualified reference for class
* Fix reference in tunnel.py
* Remove python syntax highlighting in data_converter.py
For some reason sphinx couldn't lex these as python. Removing the highlighting seems like the logical solution for now, since if it wasn't being lexed, it wouldn't highlight anyway.
* Comment out static path since we're not using it right now
* Update sphinx version in docs requirements too
Would rather remove this duplication but RTD is a special snowflake
* Docstrings for chat formatting
* Docstrings for mod utils
* Type checking
* Override CSS to highlight object name in definition
* More typing
* Utils docs pages
* Fix typo here
