From 8dcf4d5b85412d5d74ae8d4785256cc1e62487a9 Mon Sep 17 00:00:00 2001 From: Jeroen Claassens Date: Sat, 30 Oct 2021 19:49:50 +0200 Subject: [PATCH] docs: remove references to old documentation --- .github/CONTRIBUTING.md | 28 +------- .github/workflows/continuous-delivery.yml | 54 --------------- README.md | 4 -- guides/getting-started/CreatingCommands.md | 70 ------------------- guides/getting-started/CreatingListeners.md | 43 ------------ guides/getting-started/GettingStarted.md | 75 --------------------- package.json | 2 +- 7 files changed, 3 insertions(+), 273 deletions(-) delete mode 100644 guides/getting-started/CreatingCommands.md delete mode 100644 guides/getting-started/CreatingListeners.md delete mode 100644 guides/getting-started/GettingStarted.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index c4af5fad7..462a63302 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -8,25 +8,6 @@ 4. Commit your changes, and push them. 5. Submit a Pull Request [here]! -## Contributing to the guides - -All guides for the Sapphire Community use Markdown formatting. - -When writing guides there are some rules to follow: - -1. All files should have the `.md` file extension. -2. Folder names are allowed to have spaces. -3. All folder names should be in lower case and different words should be split by hyphens (e.g., `hello-world` or `getting-started`). -4. File names should _never_ have spaces. -5. File names that consist of multiple words should be PascalCased. -6. Information in a guide page should be generally useful to the majority of people. - - The single exception to this goes to guides in the "Advanced" folder, which can cover any kind of advanced or complex usage topic. -7. There are several variables that will be replaced when parsing the `.md` file for the documentation website. Variables are denoted by the pattern `{@variableName (parameter)}`. The supported variables are: - - `{@branch}` - for the current branch name. - - `{@link }` - wherein `` is a reference to some TypeScript interface / class / function etc parsed from TSDoc. This will link the API page of that symbol. - - `{@typedef }` - wherein `` is the name of a TypeScript interface, class or type. This will inline all the properties of that interface/type/class as a table, with links back to their API documentation page. - - `{@guide }` - wherein `` is the name of another guide file in this same project _without file extension_. For example linking to `CreatingArguments.md` would be `{@guide CreatingArguments}`. - ## Contributing to the code **The issue tracker is only for issue reporting or proposals/suggestions. If you have a question, you can find us in our [Discord Server][discord server]**. @@ -45,18 +26,13 @@ There are a number of guidelines considered when reviewing Pull Requests to be m - Everything should be shard compliant. If code you put in a pull request would break when sharding, break other things from supporting sharding, or is incompatible with sharding; then you will need to think of a way to make it work with sharding in mind before the pull request will be accepted and merged. - Everything should follow [OOP paradigms][oop paradigms] and generally rely on behaviour over state where possible. This generally helps methods be predictable, keeps the codebase simple and understandable, reduces code duplication through abstraction, and leads to efficiency and therefore scalability. - Everything should follow our ESLint rules as closely as possible, and should pass lint tests even if you must disable a rule for a single line. -- Scripts that are to be ran outside of the scope of the bot should be added to [scripts] directory and should be in the `.mjs` file format. - - - - [discord server]: https://sapphirejs.dev/discord -[here]: https://github.com/sapphiredev/framework/pulls +[here]: https://github.com/sapphiredev/cli/pulls [eslint]: https://eslint.org/ [node.js]: https://nodejs.org/en/download/ -[yarn]: https://classic.yarnpkg.com/en/docs/install +[yarn]: https://yarnpkg.com/getting-started/install [oop paradigms]: https://en.wikipedia.org/wiki/Object-oriented_programming [scripts]: /scripts diff --git a/.github/workflows/continuous-delivery.yml b/.github/workflows/continuous-delivery.yml index 8d4bab04e..3e8b5408f 100644 --- a/.github/workflows/continuous-delivery.yml +++ b/.github/workflows/continuous-delivery.yml @@ -57,57 +57,3 @@ jobs: npm publish --tag ${TAG} || true env: NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }} - - Docgen: - name: Docgen - runs-on: ubuntu-latest - if: "github.event_name == 'push'" - steps: - - name: Checkout Project - uses: actions/checkout@1e204e9a9253d643386038d443f96446fa156a97 # renovate: tag=v2 - - name: Use Node.js v16 - uses: actions/setup-node@270253e841af726300e85d718a5f606959b2903c # renovate: tag=v2 - with: - node-version: 16 - - name: Restore CI Cache - uses: actions/cache@c64c572235d810460d0d6876e9c705ad5002b353 # renovate: tag=v2.1.6 - id: cache-restore - with: - path: node_modules - key: ${{ runner.os }}-16-${{ hashFiles('**/yarn.lock') }} - - name: Install Dependencies if Cache Miss - if: ${{ !steps.cache-restore.outputs.cache-hit }} - run: yarn --immutable - - name: Build documentation - run: yarn docs - - name: Publish Docs - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - run: | - REPO="https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" - - echo -e "\n# Checkout the repo in the target branch" - TARGET_BRANCH="gh-pages" - git clone $REPO out -b $TARGET_BRANCH - - echo -e "\n# Remove any old files in the out folder" - rm -rfv out/assets/* - rm -rfv out/interfaces/* - rm -rfv out/*.html - - echo -e "\n# Move the generated docs to the newly-checked-out repo, to be committed and pushed" - rsync -vaI .all-contributorsrc out/ - rsync -vaI LICENSE.md out/ - rsync -vaI README.md out/ - rsync -vaI docs/ out/ - - echo -e "\n# Commit and push" - cd out - git add --all . - git config user.name "${GITHUB_ACTOR}" - git config user.email "${GITHUB_EMAIL}" - git commit -m "docs: api docs build for ${GITHUB_SHA}" || true - git push origin $TARGET_BRANCH - env: - GITHUB_TOKEN: ${{ secrets.SKYRA_TOKEN }} - GITHUB_ACTOR: NM-EEA-Y - GITHUB_EMAIL: contact@skyra.pw diff --git a/README.md b/README.md index 00a867654..430fd7a5b 100644 --- a/README.md +++ b/README.md @@ -42,10 +42,6 @@ npm install @sapphire/framework discord.js --- -## API Documentation - -For the full API documentation please refer to the TypeDoc generated [documentation](https://sapphiredev.github.io/framework). - ## Buy us some doughnuts Sapphire Community is and always will be open source, even if we don't get donations. That being said, we know there are amazing people who may still want to donate just to show their appreciation. Thank you very much in advance! diff --git a/guides/getting-started/CreatingCommands.md b/guides/getting-started/CreatingCommands.md deleted file mode 100644 index a82efd3d5..000000000 --- a/guides/getting-started/CreatingCommands.md +++ /dev/null @@ -1,70 +0,0 @@ -# Creating commands - -## Setting up the client - -Before creating the command, you should specify a prefix for your commands. -For that, you will need to add a property in your client's options, in `src/main.js`: - -```javascript -const client = new SapphireClient({ - defaultPrefix: '!' -}); -``` - -From now on, when someone sends a message that start with `!`, Sapphire will check if a matching command exists. -If you know how to use regexes, you can also add a regex prefix by adding the `regexPrefix` property. - -## Setting up the file structure - -You should now create a `commands` folder in the `src` folder. Sapphire will automatically load commands that are in -this specific folder, so be careful to copy its name properly. -You can organize your different commands in subfolders corresponding to the category. We will create one called -"General" containing various important commands for our bot. -Your file structure should look like this: - -``` -node_modules/ -src/ - ├── commands/ - │ └── General/ - └── main.js -package-lock.json -package.json -``` - -### Ping command - -To create a command you simply need to create a file with the name of the command, in our case `ping.js`, in the -category you like, such as `./src/commands/General/`. - -Each command is a class that extends from the base `Command` class from Sapphire. You need to extend it, and add a -`messageRun` method that will get called when your command is triggered. -Don't forget to export the class! - -```javascript -const { Command } = require('@sapphire/framework'); - -module.exports = class extends Command { - constructor(context) { - super(context, { - name: 'ping', - description: 'Send back the ping of the bot' - }); - } - - async messageRun(message) { - const msg = await message.channel.send('Ping?'); - return msg.edit( - `Pong! Bot Latency ${Math.round(this.container.client.ws.ping)}ms. API Latency ${msg.createdTimestamp - message.createdTimestamp}ms.` - ); - } -}; -``` - -The first parameter of `super` is the context, that is given in the constructor. You can then specify a -{@link CommandOptions} object, containing properties such as the command's name or the -command's description. - -The `messageRun` method is the method that gets called when the command is ran. It takes the message as the first argument. - -If everything was done correctly, you should now be able to launch your bot without errors and execute the `!ping` command. diff --git a/guides/getting-started/CreatingListeners.md b/guides/getting-started/CreatingListeners.md deleted file mode 100644 index 6da58f4aa..000000000 --- a/guides/getting-started/CreatingListeners.md +++ /dev/null @@ -1,43 +0,0 @@ -# Creating listeners - -## Setting up the file structure - -Sapphire loads events the same way as it loads command, by automatically reading files in the `listeners` folder. You -should now create such a folder, and add your first listeners in it. - -### Ready listener - -To create an listener you simply need to create a file with the name of the listener, in our case `ready.js`. - -Each listener is a class that extends from the base `Listener` class from Sapphire. You need to extend it, and add a -`run` method which works the same way as for commands. - -```javascript -const { Listener } = require('@sapphire/framework'); - -module.exports = class extends Listener { - constructor(context) { - super(context, { - once: true - }); - } - - async run() { - this.container.logger.info('The bot is up and running!'); - } -}; -``` - -The first parameter of `super` is the context, that is given in the constructor. You can then specify an -{@link ListenerOptions} object, containing properties such as the emitter's, the listener's name, and -whether it should only be run once (`once`). The emitter defaults to the the client, and the listener name default to -the file name. - -The `run` method is the method that gets called when the event occurs. It takes whatever the events gives as argument. -In our case, the ready events gives no information so we don't need any parameter. - -Every piece (listeners, commands etc) in sapphire has a `container` which can be accessed via -`this.container`. It is this container that contains the logger, the client and other properties. Here we access the -logger via `this.container.logger` and call its `info` method to print a nicely formatted message in the console. - -If everything was done correctly, now, whenever you launch your bot, you will see a message in the console. diff --git a/guides/getting-started/GettingStarted.md b/guides/getting-started/GettingStarted.md deleted file mode 100644 index 4ea8c4711..000000000 --- a/guides/getting-started/GettingStarted.md +++ /dev/null @@ -1,75 +0,0 @@ -# Welcome to the @sapphire/framework#{@branch} documentation - -## Installing [@sapphire/framework](https://www.npmjs.com/package/@sapphire/framework) - -You can install this version of @sapphire/framework with one of the following commands: - -**When using `npm`** - -```sh -npm install @sapphire/framework -``` - -**When using `yarn`** - -```sh -yarn add @sapphire/framework -``` - -**When using `pnpm`** - -```sh -pnpm add @sapphire/framework -``` - -Note: Sapphire requires you to have Node.js 14.0.0 or higher, and Discord.js 12 or higher. - -### Using @sapphire/framework - -Create a file called `main.js` (or whatever you prefer) which will initiate and configure @sapphire/framework. - -You can add this basic content, to create a new client: - -```javascript -const { SapphireClient } = require('@sapphire/framework'); - -const client = new SapphireClient(); - -client.login('your-bot-token'); -``` - -You can pass arguments to the {@link SapphireClient} constructor as an object. It can contain property from Discord.js' -[ClientOptions](https://discord.js.org/#/docs/main/stable/typedef/ClientOptions) as well as property from Sapphire. - -> SapphireClientOptions are merged with [discord.js ClientOptions](https://discord.js.org/#/docs/main/stable/typedef/ClientOptions) - -## Running your bot - -Once you have the basics set up run the following in your folder to start your bot: - -```sh -node main.js -``` - -You won't have any feedback on your console, and the bot won't respond to any events in discord, but it is online! - -## Preparing your file structure - -You can now organize your project correctly by grouping files together in folders. This will allow it to scale more -easily as you add commands, listeners, and other features. -The main folder, at the root of your project and containing all your code can be named `src` (for "source"). You can put -your `main.js` file inside this `src` directory and check that your bot still boots when you run - -```sh -node src/main.js -``` - -Your file structure should now look like this: - -``` -node_modules/ -src/ - └── main.js -package-lock.json -package.json -``` diff --git a/package.json b/package.json index 008a27006..484351f33 100644 --- a/package.json +++ b/package.json @@ -88,7 +88,7 @@ "bugs": { "url": "https://github.com/sapphiredev/framework/issues" }, - "homepage": "https://sapphiredev.github.io/framework", + "homepage": "https://www.sapphirejs.dev", "commitlint": { "extends": [ "@commitlint/config-conventional"