[WIP] AssetLib docs (#992)

learning/features/assetlib/index.rst

@@ -0,0 +1,10 @@
+Asset Library
+=============
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-learn-features-assetlib
+
+   what_is_assetlib
+   using_assetlib
+   uploading_to_assetlib

learning/features/assetlib/uploading_to_assetlib.rst

@@ -0,0 +1,110 @@
+.. _doc_uploading_to_assetlib:
+
+Submitting to the Asset Library
+===============================
+
+Introduction
+------------
+
+This tutorial aims to serve as both a guide on how you can submit your own assets
+to the Godot Asset Library and share them with the Godot community.
+
+As mentioned in the :ref:`doc_using_assetlib` document, in order to be able to
+submit assets to the AssetLib, you need to have a registered account, and be
+logged in.
+
+Submitting
+----------
+
+Once you are logged in, you will be able to head over to the "Submit Assets" page
+of the AssetLib, which will look like this:
+
+|image0|
+
+While it may look like a lot (and there is more to scroll down), each field is
+described in terms of what you should put in. We will nonetheless go over what
+is required in the submission form here as well.
+
+* **Asset Name**: 
+    The name of your asset. Should be a unique, descriptive title of 
+    what your asset is.
+* **Category**: 
+    The category that your asset belongs to, and will be shown in
+    search results. The category is split into **Addons** and **Projects**.  
+    In-editor, assets of the Project type (Templates, Demos, Projects) only show
+    up when viewing the AssetLib from the Project Manager, while assets of the
+    Addon type will only be visible from inside a project. 
+* **Godot version**: 
+    The version of the engine that the asset works with.
+    Currently it's not possible to have a single asset entry contain downloads for
+    multiple engine versions, so you may need to re-submit the asset mulitple times,
+    with an entry for each Godot version it supports. This is particularly important
+    when dealing with major versions of the engine, such as Godot 2.x and Godot 3.x.
+* **Version**: 
+    The version number of the asset. While you are free to choose
+    and use any  versioning scheme that you like, you may want to look into
+    something such as `SemVer <https://semver.org>`_ if you want your asset's
+    versioning scheme to be clear and consistent. Note that there is also an
+    internal version number, incremented every time the asset download URL is
+    changed/updated. 
+* **Repository host**: 
+    Assets uploaded to the AssetLib are not hosted on it
+    directly, and instead point to repositories hosted on third-party Git providers,
+    such as GitHub, GitLab or Bitbucket. This is where you choose which provider
+    your asset uses, so the final download link can be computed.
+* **Repository URL**: 
+    The URL to your asset's files/webpage. This will vary
+    based on your choice of provider, but it should look similar to `https://github.com/<user>/<project>`.
+* **Issues URL**: 
+    The URL to your asset's issue tracker. Again, this will differ
+    from repository host to repository host, but will likely look similar to
+    `https://github.cmo/<user>/<project>/issues`. You may leave this field empty
+    if you use your provider's issue tracker, and it's part of the same repository.
+* **Download Commit/Tag**:
+    The commit or tag of the asset. For example,
+    `b1d3172f89b86e52465a74f63a74ac84c491d3e1` or `v1.0`. From this, the actual
+    download URL will be computed.
+* **Icon URL**:
+    The URL to your asset's icon (which will be used as a thumbnail
+    in the AssetLib search results, and on the asset's page). Should be an image
+    in either the PNG or JPG format.
+* **License**:
+    The license under which you are distributing the asset. The list
+    includes a variety of free and open-source software liceses, such as GPL
+    (v2 and v3), MIT, BSD and Boost Software License. You can visit `OpenSource.org <https://opensource.org>`_  
+    for a detailed description of each of the listed liceses.
+* **Description**:
+    Finally, you can use the Description field for a textual
+    overview of your asset, its features and behavior, a changelog, et cetera. In the
+    future, formatting with Markdown will be supported, but currently, your only
+    option is plain text.
+
+You may also include up to three text and/or image previews, which will be shown
+at the bottom of the asset page. Use the "Enable" checkbox on each of the preview
+submission boxes to enable them.
+
+* **Type**: 
+    Either an image, or a video.
+* **Image/YouTube URL**:
+    Either a link to the image, or to a video, hosted on YouTube.
+* **Thumbnail URL**:
+    An URL to a image that will be used as a thumbnail for the
+    preview. This option will be removed eventually, and thumbnails will be automatically
+    computed instead.
+
+Once you are done, hit Submit. Your asset will be entered into the pending queue,
+which you can visit on the AssetLib `here <https://godotengine.org/asset-library/asset/edit?&asset=-1>`_ . The approval process is manual and may
+take up to a few days for your addon to be accepted (or rejected), so please
+be patient! You will be informed when your asset is reviewed. If it was rejected,
+you will be told why that may have been, and you will be able to submit it again
+with the appropriate changes. 
+You may have some luck accelerating the approval process by messaging the
+moderators/assetlib reviewers on IRC (the #godotengine-atelier channel on Freenode),
+or the official Discord server.
+
+Submission guidelines
+---------------------
+
+[TODO]
+
+.. |image0| image:: ./img/assetlib_submit.png

learning/features/assetlib/using_assetlib.rst

@@ -0,0 +1,185 @@
+.. _doc_using_assetlib:
+
+Using the AssetLib
+==================
+
+On the website
+--------------
+
+Overview
+~~~~~~~~
+
+As mentioned before, you can access the web frontend of the AssetLib
+on `Godot's official website <https://godotengine.org/asset-library>`_, and this
+is what it looks like when you first visit it:
+
+|image0|
+
+At the top you see the **header** which takes you to various other parts of the
+AssetLib - at the moment it's empty as we are not logged in.
+
+Searching
+~~~~~~~~~
+
+In the center is the **search bar + settings** section, and the **assets** section
+below it - this lets you filter out certain kinds of assets based on a host
+of criteria. These include the asset **category** (such as 2D tools, scripts
+and demos), **engine version** they are intended for, **sorting order** (by
+update date, by name, etc.) and **support level**.
+
+While most other filter settings should be fairly self-explanatory, it's worth
+going over what "support level" means in the Asset Library.
+Currently there are three support levels, and each asset can belong to only one.
+
+**Official** assets are created and maintained by the official Godot Engine
+developers. Currently, these include the official engine demos, which showcase
+how various areas of the engine work.
+
+**Community** assets are submitted and maintained by the members of the
+Godot community.
+
+**Testing** assets are works-in-progress, and may contain bugs and usability
+issues. They are not recommended for use in serious projects, but you are
+encouraged to download, test them, and submit issues to the original authors.
+
+You can mix and match any of the search filters and criteria, and upon clicking
+the Search button, receive the list of all assets in the Library that match them.
+
+|image1|
+
+Note that the search results are not updated in real-time, so you will have to
+re-submit the search query each time you change the query settings.
+
+Breakdown of an asset
+~~~~~~~~~~~~~~~~~~~~~
+
+Now let's take a look at what an asset's page looks like and what it contains.
+
+|image2|
+
+1. Asset's thumbnail/icon.
+2. Asset's name.
+3. Current version number of the asset.
+4. Asset's average rating, displayed in stars. (This is currently unimplemented.)
+5. Asset's category, Godot version, and support status.
+6. Asset's original author/submitter.
+7. The license the asset is distributed under.
+8. The date of the asset's latest edit/update.
+9. A textual description of the asset.
+10. Links related to the asset (download link, file list, issue tracker).
+11. A SHA-256 of the asset, for download validation purposes.
+12. Images and videos showcasing the asset.
+
+Registering and logging in
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to upload assets to the AssetLib, you need to be logged in, and to do 
+that, you need a registered user account. In the future, this may also give you
+access to other features, such as commenting on or rating the existing assets.
+You do *not* need to be logged in to browse and download the assets.
+
+The login/registration page can be accessed from the AssetLib header.
+
+|image3|
+
+From here, you can register your account, which requires a valid email address,
+a username, and a (preferably strong) password.
+
+|image4|
+
+Then, you can use your username and password to log in.
+
+|image5|
+
+This will change the look of the AssetLib header. Now you get access to a handful
+new functions:
+
+- The feed, which shows a list of status updates on your submitted assets (and possibly more in the future).
+- A list of your uploaded assets.
+- The ability to submit new assets.
+
+|image6|
+
+You can learn how to submit assets to the Library, and what the asset submission
+guidelines are, in the next part of this tutorial, ::ref:`doc_uploading_to_assetlib`.
+
+In the editor
+-------------
+
+You can also access the AssetLib directly from Godot. It is available from two
+places - in the Project Manager's Templates tab, and inside of a project, from
+the workspaces list.
+
+|image7|
+
+Click on it, and Godot will fetch info about the assets from the AssetLib. Once
+it's finished, you will see a window similar to what the AssetLib website looks
+like, with some differences:
+
+|image8|
+
+Similarly to the web version of the AssetLib, here you can search 
+for assets by category, name, and sort them by factors such as name or edit date.
+
+Notably, you can only fetch assets for the current version of Godot you are running.
+Also, you can only download Projects, Demos and Templates from the Project Manager
+view of the AssetLib, while Addons (tools, scripts, materials etc.) can only be
+downloaded from the in-project AssetLib. 
+
+In the future, you will be able to choose a different AssetLib provider to fetch
+assets from (using the Site dropdown menu), however currently only the official
+`Godot website <https://godotengine.org>`_ version of the AssetLib is supported,
+as well as the version that may be running on your local machine's web server
+(the localhost option).
+
+When you click on an asset, you will see more information about it.
+
+|image9|
+
+If you click on the Install button, Godot will fetch an archive of the asset,
+and will track download progress of it at the bottom of the editor window. If
+the download fails, you can retry it using the Retry button.
+
+|image10|
+
+When it finishes, you can proceed to install it using the Install button.
+This will bring up the Package Installer window.
+
+|image11|
+
+Here you can see a list of all the files that will be installed. You can tick off
+any of the files that you do not wish to install, and Godot will also inform you
+about any problems with files that it cannot install. These files will be shown
+in red, and hovering over them will show you a message stating why it cannot be
+installed. 
+
+|image12|
+
+Once you are done, you can press the Install button, which will unzip all the
+files in the archive, and import any assets contained therein, such as images or
+3D models. Once this is done, you should see a message stating that the Package
+installation is complete.
+
+|image13|
+
+You may also use the Import button to import asset archives obtained
+elsewhere (such as downloading them directly from the AssetLib web frontend),
+which will take you through the same package installation procedure as with the
+assets downloaded directly via Godot that we just covered.
+
+
+.. |image0| image:: ./img/assetlib_website.png
+.. |image1| image:: ./img/assetlib_search.png
+.. |image2| image:: ./img/assetlib_asset.png
+.. |image3| image:: ./img/assetlib_register-login.png
+.. |image4| image:: ./img/assetlib_register.png
+.. |image5| image:: ./img/assetlib_login.png
+.. |image6| image:: ./img/assetlib_login_header.png
+.. |image7| image:: ./img/assetlib_editor_workspace.png
+.. |image8| image:: ./img/assetlib_editor.png
+.. |image9| image:: ./img/assetlib_editor_asset.png
+.. |image10| image:: ./img/assetlib_editor_download.png
+.. |image11| image:: ./img/assetlib_editor_installer.png
+.. |image12| image:: ./img/assetlib_editor_installer_error.png
+.. |image13| image:: ./img/assetlib_editor_installer_success.png
+.. |image14| image:: ./img/assetlib_editor_projects.png

learning/features/assetlib/what_is_assetlib.rst

@@ -0,0 +1,35 @@
+.. _doc_what_is_assetlib:
+
+About the Asset Library
+=======================
+
+The Godot Asset Library, otherwise known as the AssetLib, is a repository of
+user-submitted Godot addons, scripts, tools and other resources, collectively referred
+to as assets. They're available to all Godot users for download directly from within the
+engine, but it can also be accessed at Godot's `official website <https://godotengine.org/asset-library>`_.
+
+On the surface the Asset Library might look and function similar to asset
+stores available for other engines, such as Unity's Asset Store, or Unreal
+Engine's Marketplace, where you can submit both freely-available assets, as well
+as paid, commercial ones. In addition, often times such assets are distributed
+under non-free, proprietary licenses, limiting what you can do with them.
+
+The Asset Library is different - all assets are distributed free of charge, and under
+a host of open-source licenses (such as the MIT license, the GPL, and the Boost Software License).
+This makes the AssetLib more similar to the software repositories of a GNU/Linux distribution.
+
+This set of pages will cover how to use the AssetLib (both from inside Godot, and on the
+website), how you can submit your own assets, and what the guidelines for submission are.
+
+Please note that the AssetLib is relatively young - it may have various pain points, bugs
+and usability issues. As with all Godot projects, the code repository is available on `GitHub <https://github.com/godotengine/asset-library>`_,
+where you can submit pull requests and issues, so please do not hesitate to visit it!
+
+Frequently asked questions
+--------------------------
+
+Can paid assets be uploaded to the asset library?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Not on the official one, though in the future there might be other asset
+libraries which allow it.

learning/features/index.rst

@@ -17,5 +17,5 @@ Engine features
    networking/index
    platform/index
    audio/index
+   assetlib/index
    misc/index
-