spongepowered / spongedocs

Documentation for Sponge and its Implementations

Sponge Documentation

This is the repository where the Sponge documentation is held.

The latest version may be viewed in full by visiting Sponge Docs

Contributing

Instructions and Guidelines on how to contribute can be found on the Docs themselves.

Licensing

The Sponge Documentation is licensed under the Creative Commons - Share-Alike license.

You can read more about our licensing situation on the documentation itself.

Translations

We're eagerly looking for translators! Please visit the Crowdin translation page, sign up, join the team, and start translating.

Local Environment

You can setup an environment so you can instantly see the changes that have been made to the docs.

1. Install Python 3
2. Install node.js

In terminal or the command line, within the directory containing this README, run the following commands:

npm install -g gulp
npm install
pip install -r requirements.txt
gulp

Your browser should open to reveal the docs. When you make a change to the documentation, the docs should refresh in the browser (possibly after a few seconds).

spongedocs's Issues

Table width unconstrained on RtD

Tables look terrible on the Read-the-Docs pages (ie. http://sponge.readthedocs.org/en/latest/users/server-properties/ ). Something is wrong with the wrapping on the last column, that does not happen on the GitHub view. Can we fix this with Sphinx or RtD style settings?

Add new Sponge commands

A recent commit to Sponge added some new commands. These should be added to our page at source/users/commands. There's some sexy documentation with the commit at SpongePowered/Sponge@be08be0
This issue shouldn't take long to deal with. Any takers?

Clean up JDK Install stuff

The pages ~/devs/forge/contributing and ~/plugins/workspace contain overlapping information presented in inconsistent formats. We might as well offload the JDK DL and install description to a new JDK page (eg, ~/plugins/javadevkit.rst).

Log examples and explanation needed

The page source/users/logs needs some Forge specifics (file-naming, logging conventions) and preferably a log example from a clean Forge 1.8.X server (and/or links to relevant Forge Wiki pages). This is aimed at server admins. Low hanging fruit, any volunteers?

Commands page needs content

The file at source/users/commands needs content. Probably a link to MC Wiki for all vanilla commands.
Any specific sponge commands and their permission nodes (if any) need to be added. Forge too.

Images in FAQ not found

The pictures in the faq page appear missing with a 404 error.

Transition from ide-specific plugin setup to using gradle/maven

Not to pick on anyone, but here's a conversation that happened in #dev:

The tutorials on setting up IDEs should lead up directly into using gradle/maven, most likely with a recommendation to use gradle(for ForgeGradle)

Redundant .pot Files pushed to Transifex

Files that are renamed or moved leave behind a ghost .pot file in the build sent to Transifex.
This is a problem because (i) it bloats storage, (ii) it wastes bandwidth, and importantly (iii) folk might translate redundant files. It isn't a severe issue, Transifex just has just too much *.pot.
Our esteemed @gratimax may have ideas for a solution.

Switch to using crowdin

So transifex is a bit of a bummer when it comes to uploading/downloading stuff. It's pretty slow, and I have also had to fork the client in order to get it to do what I want(not very appealing). We are trying out using crowdin, which boasts more features and an overall nicer GUI. It is also the system used by Minecraft for their translations.

Interested for input from contributors and translators.

Add Granite Page(s)

(From the Forums): A few pages have already been tweaked to mention Granite, and having its' own Docs page would probably be justifiable. Where the Granite implementation diverges from the nascent Forge implementation, an explanation would be appropriate for users.

Please bear in mind that the SpongeDocs are intended to be largely implementation-agnostic where possible. We're providing info on the Forge implementation largely because the same team are writing it and the API. We don't plan to provide large amounts of detail on other implementations. Preferably third-party implementations (such as Granite) can provide a nice friendly website of their own to help users install and use it, and we can put a link in SpongeDocs.

Please let me know if there are any further complications AzureusNation & others.

Working with the Message API

I have made a stub file for explaining the Message API at source/plugins/message. Please help elucidate this file if you are able.

Flesh out debugging, plugin & spongedev

Parameters for Sponge Commands

Following on from #89, the parameters of the new Sponge commands need to be added to the Table at source/users/commands.rst. Details and some examples are found at SpongePowered/Sponge@be08be0
The examples would be useful to add to the page at users/config instead.
(A new page for Sponge commands may be justified if it gets much bigger.)

Plugins: Best Practice Guide needed

Discussing plugins that depend on more than Sponge is going to be a can of worms. They are likely to break compatibility all over the place. We don't want to have to put boilerplate warnings everywhere. To help avoid some of this, a Sponge Plugin Best Practice / Style Guide may be helpful. (Rhetorical questions:). What's wrong with using NMS, Forge, or some other API in a Sponge plugin? What is the position with Libs and Scripts? We'd love all plugins to be 100% compatible with all implementations of the API. But the experience of Craftbukkit shows us otherwise, and we may have to deal with it eventually. Warnings on Initialise? Who knows. Any suggestions and contributions here are welcome.

Command Registration needs content

A walk-through of the Registration of Commands in Sponge Plugins is required in the page at source/plugins/commands.

Explain Port Forwarding

The page at source/users/port-forwarding is now linked to from quick-start. A basic walk-through of Port Forwarding is needed here, and a link or two to good sites to go to for hardware-specific help. eg. http://portforward.com/

Plugins page needs a Plugin repository

The page /users/plugins needs a link to the Sponge Plugin Repo, which does not yet exist.

Block API explanation needed

The Block API section is blank, on page /plugins/blocks. It needs filling in by a wise dev person (if and when we have a working block API).

Event-Bus: Firing Events etc - text needed

The page source/plugins/event-bus has some text (from sk89q), but the part on Firing Events and below is blank. Would some kind and knowledgeable soul please fill these parts in, or re-write this doc?

Services page is blank

The page at source/plugins/services needs some information. I invite anyone who knows whatever it is that should be here to put it here forthwith.

Need plugin-developer pages from FLARD planning doc

The FLARD plan (at REDACTED) calls for a new set of tiers for the dev pages. We should rename the whole directory to from developers to plugin-developers at this stage.Also omit the redundant tier Building Plugins.

Working with the Plugin Manager

The new stub at source/plugins/manager needs an explanation of how to Work with the Plugin Manager. Who feels up to the challenge?

Docs FAQ needs overhaul

The google Doc FAQ at https://docs.google.com/document/d/1VJ1WzHI-VUuoHEJz4SRHUbl-5XnsURbqP5fIi8B4Kyg/edit is better than our current Docs version, and updated in most places. It has nice tables and stuff, that may be fun to port into rst.
We can keep the FAQ as a Google doc, or port it to SpongeDocs (latter seems preferable).

HOCON page needs more info

The HOCON info page at source/users/hocon needs a bit more friendly text, and an example or two. Folk will want to know how does HOCON format differ from YAML or XML?

How do we want the changelog page to work?

When we have a changelog for Sponge, we'll need a way of making it available to SpongeDocs.
Options: (1) Link to another page, eg. a Jenkins changelog (2) uploading each file to Docs (preferably automated) and adding to index. Anyone else got any bright ideas, or preferences?

Need Contribution Guidelines

Someone well versed in the coding of Sponge needs to detail the Contribution Guidelines (for adding to Sponge or Sponge API). This may involve some argy-bargy amongst yourselves to work out exactly what you do and don't want to see in new Pull Requests, etc.
I blame DarkArcana for this.

Docs theme: minor suggestions

I just had a look at the new Docs theme and now have some suggestions to improve it further:

-index (genindex.html) in the top right corner should be replaced with index.html
-prev and next isn't needed as we have a global toc and tracks
-update of the code snippets div to make it look like the Tips and Warnings div (no rounded edges, border-left:4px)
-the search button seems to be a tad off (1px too less height, 1px to the bottom)
-the toc might look better with a depth of only 2 (like the RtD Theme)

Update configuration pages to use configurate

The current configuration pages describe using Sponge's own ConfigFile, which wraps around the typesafe API. This should be changed to instead use configurate's ConfigurationLoader, which is what is now used.

I would update this myself, however I have little experience with either: I was just reading through the docs and noticed this.

Add a link to docs.spongepowered.org

Currently, there's no link to docs.spongepowered.org in either the README, or to the right of the Github organization and project name SpongePowered / SpongeDocs

Getting a Logger: description needed

On the page source/plugins/logging, the section "Getting a Logger" and below is blank. Could some well-informed developer please complete this section?

Plugin Config page needs writing

The page at source/plugins/configuration is intended for discussion of working with Configuration and defaults in developing Plugins. From the original Wiki plan. Someone please write this!

How to work with Entities

Page stub needs expanding at at source/plugins/entities (Working with Entities). Would some generous and well-informed developer please provide some instruction?

Plugin Lifecycle needs correction of running states

Just tried to translate Plugin lifecycles and noticed that headings and described events don't match:

-SERVER_STARTED mentions ServerStopped Event
-description of SERVER_STARTED and SERVER_STARTING is almost identical (only events differ)

Compress Migration to Sponge Pages

The page users/compat is a launchpad for pages to explain migrating your server from Forge, Bukkit and now Canary, to a Forge server running Sponge mod. These could be compressed into a single page, and we should add mention of Spigot and Cauldron. (Is it conceivable that anyone would migrate from Granite or Glowstone in the future?) Migrating to other implementations of Sponge may be a useful addition later too.
TL;DR Summary of my plan here:

• Combine Bukkit and Canary pages into Forge page, expand to add other servers.
• Keep Compat page (add migrating to Glowstone and Granite pages when appropriate).

Helping Out page needed

The last FAQ is "How Can I Help Out?" and the information after it is outdated. It needs updating from the various teams (SpongeDev, Wiki, Forum). I think we should shorten it to a link to a new page somewhere, and break down how they can contribute (Forum, Wiki, SpongeDev, Plugins, bribes...). Basically a Volunteers Portal, where we can spruik for new staff.

Example sponge.conf needed

We need an example sponge.conf file and an explanation of its properties for the page /users/conf

Move Workspace Setup Information to a central page

There are multiple pages explaining how to download and use the JDK, IDE, git, gradle, etc.

It's always the same procedure, for plugin development and API/Mod development.

I'm suggesting:

• Page about JDK installation
• Page about Gradle (download command line, alternative IDE plugins, brief tutorial)
• Page about git (download, command line, alternative IDE plugins, brief tutorial)
• Page about Eclipse (download, recommended plugins, first project tutorial)
• Page about IDEA (download, recommended plugins, first project tutorial)

We can keep the separate "Workspace Setup" pages for Plugin, Forge Mod and API development, and add links to the 5 suggested pages.

Permissions API Page for Plugins

We need a walk-through of the use of the Permissions API on the page source/plugins/permissions. Best PR gets an imaginary cookie.

Explain dependency injection and modularization

I think Sponge plugins have to use dependency injection to get the game object or the plugin logger (what else?).

We have to explain that.

Also, we should explain how to outsource parts of your plugin to other classes (pass plugin and logger object)

License.rst needs to be written

Someone better versed in the legal technicalities of MIT versus GPL should really write this. It needs an easy-to-understand explanation of the basics of the MIT license, and then some ugly nitty-gritty about why we are using it for Sponge. Plugin Developers in particular need to understand the implications.

Markup in search results

The search results include format elements like ==== , .. note:: or *. Example:

Writing a Plugin
================ Writing a Plugin ================ .. tip:: Read 
:doc:`../../workspace/index` to prepare your workspace for plugin development! 
.. note:: The instructions within the Sponge Documentation assume that you have prio...

I think the search results should be unformatted plain text.

Mixins for plugins?

Are mixins actually going to be exposed to sponge plugins? or should that section be moved to the section on developing for the sponge implementation?

Add a make.bat equlivant for Mac OS X

The Grand Scheme

This is the latest planning Document for SpongeDocs. Nothing is set in stone, but it's a good starting point. Many things need attention, some are already issues here.
https://docs.google.com/document/d/1_iKb3xL4itTS2HNpKTL7TvkTPk6aMzflqufpLAMqCDU/edit?usp=sharing

Tracks?

To be honest, while tracks are pretty neat, I find them to be a bit convoluted and hard to follow. It's unlikely that most documentation readers will be patient enough to read through all of the tracks. I suggest looking at the structure of the django documentation. It's simply split up into sections of content that is similar, as well as a tutorial at the beginning. I propose to move to a structure similar to this(potentially for end users as well?)

Language Support for SpongeDocs

Read-the-Docs defaults to the English version for the current pages. There are presently no non-english translations that I am aware of, we need to enable this so there can be some. How do we go about providing translated pages? Is there a plan somewhere?

Documentation of Implementation

Some of the API is actually only demonstrated during it's implementation in Sponge, while some team members think these docs belong in the API javadocs too, I think these details should at least be documented in the non-javadoc docs, possibly those docs should be in the javadocs as well. But I wanted to see what other people think before I start seeking out a list of required implementation details.

For those who need examples these are a few:

• Dependency injection details (exactly what classes and where)
• Plugin container format (jar layout, metadata, etc)
• Official list of implementation identifiers for plugins to customize behavior

Ping @SpongePowered/developers for comment on this, it's mostly a developer question.

Tutorial how to share plugin source code on GitHub

I think it would be good to have a step-by-step guide for "Open Source Plugin Development". This will motivate unexperienced plugin makersThe guide should be simple (one IDE, gradle-only, use GUI when possible):

1. Setup Workspace (JDK, IntelliJ [?], other tools - refer to other pages)
2. Create GitHub repo (License, README)
3. Clone repo
4. Setup Gradle project (build.gradle, dependencies - refer to other pages)
5. Write basic plugin (refer to other pages)
6. Commit, Push to GitHub
7. Debug plugin within IDE (refer to other pages)
8. Build plugin with gradle
9. Publish to Sponge plugin repo (include GitHub link in description, this should have its own page - refer to it)

Advanced Stuff (maybe separate pages):

• git command overview with use-cases and explaining graphics
• Explain GitHub pull requests, issues
• How to fork other plugins and send pull requests

SpongeDocs README needs to be updated to reference CrowdIn

Stop calling everything FLARD

Please and thank you.