Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Skript Enhancements #2519

Closed
wants to merge 16 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
.DS_Store
/node_modules/
/src/node_modules/@sapper/
yarn-error.log
/cypress/screenshots/
/__sapper__/
61 changes: 42 additions & 19 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,51 @@
# Skript Documentation Templates
# Skript Documentation

Skript's features are documented directly in it's Java code. But we still need
Here is the source code of [Skript website](https://skriptlang.github.io/Skript/).

1. HTML, CSS and (possible) Javascript code to create website out of these
2. Clear tutorials, not just "you can check the syntax pattern"
3. Examples explained, if needed
What the website uses:

When generating final result, each HTML file is surrounded by template.html,
which provides head element, navigation bar and so on.
* Bulma
* FontAwesome
* Svelte
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documentation website must work without Javascript, or at very least there must be alternative that works.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Modern websites use javascript. What's the problem with javascript?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not necessary for static pages. For dynamic features such as search, there is no alternative.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with you. But modern technologies (as react, and here svelte) use javascript to create modules. These modules are render on the website directly. So without javascript, Svelte, react and more component technologies will not work.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At least React supports rendering static content on server. Most frameworks do, though I don't know about Svelte.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Svelte too. Svelte is compiled using a bundler (as webpack or my favorite, rollup) into a static js file, what the website is using.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in this context, static doesn't mean that the files are the same every time - it means that the site has no dynamic content (like DOM manipulation and such via JS). The reason we don't want JS is because it just isn't necessary - it increases page load and parse times for no real benefit for a site as simple as Skript's docs.

Copy link
Contributor Author

@Olyno Olyno Oct 11, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm agree with you, but we could add more features later, that's the reason of my choice.
I forgot to say that the size doesn't matter. Sapper uses service workers and cache any content. So the javascript is cached into the client's browser. It's really faster. Plus, svelte is probably the smaller javascript librairy existing (comparing to react, vue etc...)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Web browsers are pretty good at caching static pages too. What I'd like to see is static pages with dynamic features implemented in JS. If that is not feasible, static pages when JS is not enabled, otherwise everything done with JS. If even that can't be done, two sites for browsing docs wouldn't be any worse than current situation. In fact, I suggested the last option when you were initially working on this PR.

* Sapper

## Template Patterns
## Export Documentation

Patterns have syntax of ${pattern_here}. For example, ${skript.version} is replaced with
current Skript version. Please see below for more...
To export the documentation, run these commands in your terminal:

You can also include other files by using ${include <filename>}. Just please make
sure that those included files don't have tags which are not allowed in position
where include is called.
**Using NPM:**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

People exporting documentation should not be required to install anything in addition to Minecraft server + Java.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll clarify this a bit: currently, on Linux, Windows and Mac, Skript needs JDK 8 or newer to be compiled. Gradle wrapper provides Gradle, which in turn provides all compile-time dependencies. So, only JDK needed to produce a usable jar.

Spigot installation is, at the moment, needed for generating documentation. We could probably get rid of this, though, and just prepare classpath with dependencies (Guava, etc.) in build script.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documentation should be not related to any minecraft server

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the doc site is generated within the plugin itself, so it runs where the plugin runs (a minecraft server)


## Pattern Reference
```
skript.* - Information of Skript
version - Skript's version
include <filename> - Load given file and place them here
generate <expressions/effects/events/types/functions> <loop template file> - Generated reference
content - In template.html, marks the point where other file is placed
npm install
npm run export
```

**Using YARN (recommanded):**

```
yarn
yarn export
```

It will generate the website as static website at ``__sapper__/export``.

## Contribute

### Edit documentation

1. Replace ``/src/utils/docs.json`` file with the new one
2. Enjoy!

### Add a contributor

1. Go in the ``/src/utils/developers.json`` file
2. Like others, add yours
3. Enjoy!

### Add a tutorial

1. Go in the ``/src/utils/tutorials.json`` file
2. Like others, add yours
3. Go in the ``/src/routes/tutorials`` directory
4. Like others, write your tutorial page
5. Enjoy!
5 changes: 0 additions & 5 deletions docs/classes.html

This file was deleted.

5 changes: 0 additions & 5 deletions docs/conditions.html

This file was deleted.

224 changes: 0 additions & 224 deletions docs/css/styles.css

This file was deleted.

33 changes: 0 additions & 33 deletions docs/docs.json

This file was deleted.

5 changes: 0 additions & 5 deletions docs/effects.html

This file was deleted.

5 changes: 0 additions & 5 deletions docs/events.html

This file was deleted.

5 changes: 0 additions & 5 deletions docs/expressions.html

This file was deleted.

10 changes: 0 additions & 10 deletions docs/functions.html

This file was deleted.

Loading