Skript: Get Skript documentation up

[bensku]

• [x] Research and select HTML template library, or create custom solution
• [x] Write static HTML and CSS for documentation site
• [x] Write Java code to insert annotated documentation to these files
• [ ] Write some tutorials, like in Njol's Skript docs, but updated
• [x] Set up Github Pages and finally upload documentation

Help would be appreciated, especially with HTML and CSS parts. This is long term project, please don't expect it to be done anytime soon (if ever). It is something I'd really like to do, since right now some features are not documented at all outside of Java code!

[TheBentoBox]

I don't know much about GitHub Pages, but I'm more than willing to help with the actual web development and writing up tutorials. I have a decent amount of web dev (HTML5/CSS) experience and even more JavaScript experience.

[bensku]

Ok, I'll update here when I have necessary Java parts ready. Thanks!

[Namnodorel]

I could also help with the docs, because I and some other people I work with require them ;) I have basic HTML/CSS (and PHP, if that matters) and medium Java experience, but havn't worked on generating docs from source code so far. Could I be helpful?

[bensku]

Yes, all HTML/CSS/Javascript help is welcome. But since you are not familiar with Skript's (quite complex) documentation output system, you'll need to wait for me to do groundwork...

I might have time to create basic stuff tomorrow, so you could start creating CSS and static content :)

[Namnodorel]

Okay, what I've reverse-engineered so far: Every expression, condition, etc. is already in-code documented. The doc/Documentation class generates a SQL Database from the annotations, if the server is in debug mode. Now a seperate Java/PHP (...?) program is supposed to generate the HTML documentation from this database. Is the progress/code of this program somewhere available? It'd help me understanding what is required ;)

[bensku]

No, it is not available. Should be easier to just write some kind of template engine in Java - coming soon™ (well, not that soon if I continue to be busy).

[bensku]

Hmm, now I have thought about the site layout more.

• It needs to have top navigation bar
• On expressions/events/effects/types/functions pages (aka reference pages), it needs sidebar like on Njol's site
• I'll write basic custom template engine

Currently all HTML "full". My (upcoming) template engine will just merge template.html and the other HTML file and name result using other file's name. Thus, if you need to touch head element, that happens in template.html.

Navigation bar will be inserted at top of each page in template.html. It is specified in navbar.html; currently TODO.

Then we have reference documentation... For each element to describe, no matter if it is expression, event, type or something else, desc_full.html is inserted to page. You can see it for more information, should be pretty easy.

Now, for what I do need help? Mostly design stuff, I'd like the site to look good. So, would someone be willing to write necessary CSS code and create cool layout for the website?

[Namnodorel]

I could try to make some CSS code, but I will probably be unable to code anything until next week. Do you have any preferences how the site should look like (for example flat blue and material theme like)

[Pilvinen]

Imo, it could look pretty much the same as the original Skript documentation page.

http://njol.ch/projects/skript/doc/effects/

[Namnodorel]

I had some unexpected time and wrote some CSS and an example page https://github.com/Namnodorel/SkriptDocs ;) Does it look like what you need?

[bensku]

Data structure (HTML code) and layout are good. Color scheme is maybe too sharp, though.

But this is still really, really helpful. Documentation pages need not to look that fancy. Integrating this to template system will be easy enough for me, even if I'm bad at CSS :) I'll do that and implement template system Java parts as soon as I have time.

Then we have up-to-date Skript docs, finally!

[Namnodorel]

I haven't really worked on the colors, just used the default blue from CSS because I thought a blue-style documentation would look good ;) The only color where I didn't use a default one is the grey of the code part, because the default grey was still too dark. Anything beyon that I should improve?

[Namnodorel]

Okay, I changed the color scheme a bit and also made the navigation floating ;) I'm not sure about the second one, is it appropiate?

[bensku]

Better now. Floating navigation bar is not working very well on mobile, but I'm sure it could be fixed quite easily.

Otherwise... I don't think anything needs to change :) Generally, this is good enough.

[Namnodorel]

Navigation is no longer annoying on mobile devices ;)

[Namnodorel]

Just to be sure you noticed it (because I saw pattern_element.html and the template): You can put the pattern in the table without the ul and li tags, if you have just one pattern. The list is only for multiple patterns for the same expression, because I thought it wouldn't be clear enough that there are multiple patterns if they are just divided by a linebreak (and if a pattern creates an overflow, there will also be automatically be a linebreak added ).

[bensku]

Yeah, I figured that out eventually :)

Next thing to do: template engine. No ETA, since my laptop doesn't even compile Skript...

[bensku]

This was delayed a lot since I wrote new updater for Skript. But soon!

[bensku]

Needs testing by me, code is ready.

[bensku]

It works!

I need some help now, though. Someone needs to write HTML and CSS for navigation bar that comes at top of the all pages. Currently you can't traverse between different documentation pages. Take look at docs/templates/navbar.html. Its contents will be pasted on top of each page.

Pinging @Namnodorel since you made rest of HTML and CSS. Willing to do a bit more? :)

You can make Skript create docs yourself:

1. Clone Skript's source somewhere
2. Copy docs folder to Skript's plugin directory on your server AND rename it to doc-templates
3. Start the server and run "/sk gen-docs" (if it is not found, didn't do step 2)
4. You have docs in Skript's plugin directory under folder docs

To regenerate docs, use the command again.

[Namnodorel]

I am :) Should it just contain the links to the other documentation pages or also something else?

Edit: Problems :/ More information at #164 Creating the navigation should be done pretty fast. But without being able to "build" them myself or at least to download them from somewhere...

[Namnodorel]

Ok, it finally works! ^^ Although the IDs and the table of contents navigation still need to be inserted.

But the navigation is there, as requested! ;) The latest commit contains all necessary changes.

[bensku]

And the documentation is up. Might need some polish, but IT WORKS!

Needs tutorials, though.

[Namnodorel]

Works...kinda. Most links are broken, and the on-page navigation still isn't there :/

I'm afraid I won't be able to write tutorials... Because I'm German and although my english is relatively good (I think) I would probably make too many grammar mistakes, which wouldn't give new users a good first impression.

I think I'm also gonna look into the color schemes again... The docs don't look that bad at the moment, but it's still a little too sharp and not so comfortable to read.

[TheBentoBox]

@bensku Think we can close this since it's all done except for the tutorials, which we now have another issue for?

[bensku]

Yeah, good idea.