News skUnity Docs - a huge update

  • Welcome to skUnity!

    Welcome to skUnity! This is a forum where members of the Skript community can communicate and interact. Skript Resource Creators can post their Resources for all to see and use.

    If you haven't done so already, feel free to join our official Discord server to expand your level of interaction with the comminuty!

    Now, what are you waiting for? Join the community now!

BaeFell

I'm Poppy
Staff member
Admin
skUnity Legend
Nov 27, 2016
1,022
241
73
discord.gg
Discord Username
BaeFell
skunity_docs_small.png


skUnity Docs - a huge update

Hi everyone,

Wrong and I have been working hard at creating the latest and greatest features for skUnity Docs. These new features allow addon developers to easily manage their addons, syntax and more, while also letting users interact with addons on a greater scale. An old feature from the original version of docs has made an appearance too!

smartdocs_small.png

The first feature I'm proud to announce is SmartDocs. SmartDocs is the 'brand' of which multiple tools we have created live under. These tools automate the docs process for you and lets you as an addon developer, focus on creating rather than documenting.

SmartImport

The first tools is SmartImport - this tool lets you have your addons syntax on the quickly and easily. Best part is - you don't have to do a thing. Unlike the usual way of manually creating the elements or the tedious task of importing JSON, SmartImport updates your docs whenever you update your resource on the forums.

While I've done a lot of testing and tinkering with SmartImport, it is prone to some slight reading issues. It is sometimes unable to figure how to parse an element successfully, but does its best. Here is what SmartImport is able to read to upload to docs:
  • Using just Skript.register<type>(...)
    • SmartImport has proven pretty reliable for being able to understand what is going on, however, is unable to parse where using a variable for the anything of the parameters. SmartImport is not setup to look for custom registering systems that are a wrapper to Skript.regsister<type>. If you use a custom way, please PM me to have it added
  • SKU.parseData()
    • Depending when this thread is actually posted depends if this is available. SmartImport seems to be good at reading this as it's custom designed for skUnity. There are rare cases where it might miss some stuff, but it's only when done weirdly.
  • Just annotations
    • SmartImport can read annotations and create an element from them. Using the default Skript ones and I have also added some mixed ones one like Syntax(es) and Pattern(es). I'm also at working with addon developers to support other annotations. For example - when SmartImport sees @SkelletProxy, it adds SkelletProxy as a requirement for that element.
  • Skript.register<type>(...) and annotations
    • During testing, I was made aware some developers use Skript.register<type>(...) to actually register the class, but use annotations for providing extra information of a class. SmartImport combines this data to upload to docs.
SmartTags

Unfortunately this feature is still in testing but we are expecting to launch it shortly. Here's what SmartTags will be though:
A common complaint that crops up is search is buggy because it doesn't differentiate between the correct British spellings and incorrect American spellings of words. Because of this, we've created SmartTags. This feature runs when a new element is created but has also been setup to run across the entire skUnity docs. If SmartTags finds a word which is knows has a alternate spelling, the alternate spelling of said word is saved. When users do a search, the search will look at the tags as well as the name and description. SmartTags is also designed to pickup important words and tag them to provide more accurate search results.

JSONImporter
Utilising the JSON exporting feature in TuSKe, you're able to copy and paste your JSON dump onto skUnity and have skUnity import it into the docs. When you click continue, the docs will take you to a checkout page. This lets you double check everything is okay and also flags up any potential duplicates where the importer is unable to find an exact match. (Inspired by @bi0)

AND MORE...

That's not all! We also have many more features to unveil here. At skUnity, we don't post about bug fixes or tiny things, we go big. This update is probably bigger than the Docs 2 update!

ResourceSync
The docs now talk to the forums in more and more ways. By allowing this communication, we have created ResourceSync. This allows you to connect your docs addon with your forums resource. ResourceSync lets the docs get information from your resources page and use it on the docs. This is the feature that powers SmartImport and another feature just below :emoji_wink:

Addon Pages and Addon Followers
Yes, that's right! Addon Pages are back. We originally never included this with Docs 2 due to multiple reasons. One of the biggest being unable to think of a good design frame for them. With the inspiration from @TonyMaster21 - everyones favourite walrus, @Wrong, has created a masterpiece. Addon Pages use ResourceSync to provide information from your resources directly on a page for the docs. Linking the docs and forums closer together.

Another feature that launches with Addon Pages, but has existed with the launch of Docs 2, is Addon Followers. Users are able to follow an addon. When that addon has a new element created, it can be seen in the Activity Queue (those announcements expire automatically after 7 days). All users following can be constantly kept up to date with their favourite addon. We are also looking at allowing Addon Developers to utilise Addon Followers and the Activity Queue to communicate with their followers.

My Addons and Addon Pages Editor
We have made it easier than ever to manage your addons and create addons. Using the admin panel of the docs, you'll notice a new section on the left hand side - My Addons. This area lists all your addons, lets you enable Dev Mode (hides your addon from the docs, perfect for testing), lets you change your addon colour, lets you see how many of what elements you have, lets you connect your addon to your forums resource and enable/disable SmartImport.

Another new feature within the My Addons section is creating an addon. This can now be done effortlessly. Once submitted, your addon will need to be approved by an admin. And once that is done, your addon is created on the docs properly and you are then able to start documenting it.

Through the My Addons section, you can access the Addon Pages Editor. This lets you specify a subtitle and 3 title blocks, plus some external links. It's easier to just sync your addon and forums resource, which skUnity will do the rest as to displaying your addon page, but the option is there! If you'd like to see something made editable or added, please let us know. (Inspired by @TonyMaster21)

Element Review
You are now able to review all your elements, see any that have missing bits of information and easily double check everything is correct. This can be accessed through the My Addons section. By default, all elements are set to false. There is no difference between a reviewed and unreviewed element, just that you've double checked its all okay.

DocsHistory
With the launch of Resource Staff, a requested feature was to see who edited what. This has been added as a feature called DocsHistory. All edits done to a syntax element are logged and viewable. DocsHistory data cannot be deleted by Resource Staff or Moderators, and we currently intend for the information to always kept, but depending on how much is saved, we may start purging older records. (Inspired by @LimeGlass)

Refreshed skUnity Homepage
Even though we've only just made a new skUnity Homepage (https://skunity.com), we have remade it again! The page has been revamped to give an overview of features offered by the docs and lists some upcoming features too. We are hoping to constantly renew the homepage in an effort to keep the front of the skUnity docs as fresh as possible.

Downloads Page
Another new feature added to the docs, is a an easy to use downloads page. It lists versions of Skript from bensku's fork on Github with a download link straight to them, plus a list of addons with their versions and a download link via the forums (downloads should still be counted properly). Access it here!

Bug Fixes and Improvements

Along with loads of new features, we have made multiple bug fixes and improvements to skUnity Docs! These include things were we've fixed an issue/bug or made an improvement to an existing feature. Here is a rundown of the ones that came off the top of my head (as we have made multiple since the last update, just don't broadcast it unnecessarily):
Fixed bugs with search

Some search queries would fail or be misunderstood by the search processor. With these fixes, I hope search becomes more reliable. Experiencing weird search results or have an idea? Contact us using the list of ways below!
Added support to use type as a replacement of category

To help people make more sensical search queries, you can now use type to search by effects, events etc, or to have search look in name, description, pattern etc. (Requested by @Pikachu)
Added hasexample:<true/false>, type:example, category:example to search

Search now has more connections to examples of elements. As these are stored in a different table to the actual elements themselves it meant search just usually returned but ignored them. Now you can add a parameter to ensure the element has an example or search through an example by using category (or type):example. (Requested by @Pikachu)
Fixed negation for some search parameters

Some search parameters ignored negation and did not return correct results. This issue has been addressed and should be resolved. If you continue to experience results you that are not matching your search query because of negation, please contact us. (Reported by @Pikachu)
Added more depth to DocsHistory

While DocsHistory has only just been publicly released, it has been internally available for a while, as such, an improvement was made to provide more depth to DocsHistory by logging who or what created/edited the element. For example, if you edit it via the website itself, you'll be logged as editing the element. But if you create an element via DocsAPI or SmartImport, that'll be logged as the reason.
Fixed an XSS bug with examples (NOTICE TO API USERS)

We were recently made aware of an XSS bug with examples and how they were outputted. As such, formatting on examples was disabled as a precautionary measure to prevent any abuse of the bug. While nothing malicious was done, we have rolled out an update that updated all examples to ensure they're safe to output regardless. We have also updated how we output examples so that they're outputted with format and are safe.

NOTICE: If you utilise the skUnity API and output examples, please note that they will return with the HTML character codes (for example, " becomes &quot; ). It is up to you to fix it when outputting. This is to prevent any abuse with the API for utilities that don't sanatise the output.
Improved loading times for forums content

With the creation of ResourceSync, I was able to allow the docs and forums to connect more. As such, we've been able to reduce loading times due to the docs fetching data from the forums. We're still working on updating many different functions in which the docs get this data, but a majority now operate on a faster connection.
Improved example editor

@Wrong has done improvements to the example editor to make it work more reliably and provide a better way to edit examples. If you experience any issues with the example editor or examples themselves, please contact us.
Improved admin panel edit page

As part of the Element Review, we have added the ability to specify an element you want to edit via the URL. This lets you quickly access that element to edit rather than searching for it. We are looking at incorporating this feature into the docs feature itself, so you can edit all your content quicker.
Adding more announcement types to the Activity Queue and more features

Originally, the Activity Queue would only show announcements in a set way. Now, the Activity Queue supports new element creation, approving/deny content and suggestions from skUnity. These allow us as staff and users across the site to do more easily. The Activity Queue is a hub of information for the docs.

Announcements made on the Activity Queue automatically expire after 7 days of creation and can now be dismissed! Some announcements cannot be dismissed, may not expire or may have a longer expiry date. This just depends on the type of announcement.

In-progress: entire docs data update
Along with many updates to the docs themselves, we will also be rolling out updates to the docs data. Skript will be updated to the latest version by bensku and other addons via SmartImport will be automatically updated to ensure any addons that have missing data are bought back in.

Coming Soon: DocsLog
Unfortunately this feature was unable to be released at this time - but we're actively working on getting it out. DocsLog provides a backup and rollback of docs data. This ensures addon developers can fix any mistakes they make when using SmartImport, JSONImport or DocsAPI, can rollback any issues they have with an edit made or if they muck up editing, they can always go back. We do not have an ETA for DocsLog as we are also trying to finish up other features across the docs.

Side update: forums now utilise a CDN for loading content and file downloads
This update was handled @Sam and has moved content from the forums server to a CDN. This allows for faster downloading of files and viewing of content (such as images loading when browsing the forums). This is because the CDN is hosted away from the server that hosts the forums which frees up resources of the forums server.

That's all folks!

And that is it! What a huge post... 13,746 characters from that "huge post...", bit. Like I said at the top of thread - we prefer to make 1 big post detailing everything, and here it is! Please enjoy the features we've created and released. We have many more planned and in the works.

If you've got a suggestion or bug to report, you can either:
PM @Wrong and I
Contact us on skUnity Discord (using channels #docs-talk or #skunity-bug-report)
Reply to this thread
Create a thread in Suggestions and Feedback

Thank you for reading! Do enjoy,
BaeFell and Wrong
:emoji_kiss:
 
With the implementation of allowing users to add their own Addons to the documentation, are we able to start putting API Scripts (Such as "json.sk" and "titleapi") in the docs?
 
With the implementation of allowing users to add their own Addons to the documentation, are we able to start putting API Scripts (Such as "json.sk" and "titleapi") in the docs?
We currently don't support script API's. Will look into adding support for them soon enough.
 
Small update: SmartImport reliability increased
Thanks to @LimeGlass for reporting that SmartImport was missing elements from his addon, FunkySk. By reporting this issue, the bug in SmartImport has been resolved and SmartImport has increased reliability in its importing of addons.

If anyone else experiences any issues, please let me know.
 
  • Like
Reactions: LimeGlass