Remove package starter kit documentation files;
Update documentation to reflect package manager release
This commit is contained in:
Matt Schoen 2020-01-03 17:59:07 -08:00
Родитель 5690d2ec61
Коммит 0caf0df616
14 изменённых файлов: 8 добавлений и 446 удалений

Просмотреть файл

@ -1,4 +0,0 @@
* [UPM Package Starter Kit](index)
* [Guide for features packages](tools-package-guide)
* [Guide for sample packages](sample-package-guide)
* [Guide for test packages](test-package-guide)

Просмотреть файл

@ -3,7 +3,7 @@ An XR-Optimized line renderer that is also capable of producing very inexpensive
## Setup and usage
1. Place the XRLineRenderer folder into Assets\XR Utilities\XRLineRenderer in your project.
1. Import the XRLineRenderer package in your project.
2. Add a XRLineRenderer or XRTrailRenderer component to your gameobject. The interface is nearly identical to the built in Unity Line and Trail Renderers.

Двоичный файл не отображается.

До

Ширина:  |  Высота:  |  Размер: 29 KiB

Двоичные данные
Documentation~/images/example.png

Двоичный файл не отображается.

До

Ширина:  |  Высота:  |  Размер: 51 KiB

Просмотреть файл

@ -1,157 +0,0 @@
# Package documentation guides
Use these guides to create preliminary, high-level documentation meant to introduce users to the feature and the sample files included in your package.
There are several types of packages:
* Packages that include features that augment the Unity Editor or Runtime (**modules**, **tools**, and **libraries**).
* Packages that provide **tests**.
* Packages that include **sample** files.
* Packages that contain **templates**.
> **Note:** Use the specialized [com.unity.template-starter-kit](https://github.cds.internal.unity3d.com/unity/com.unity.template-starter-kit) starter kit for templates.
Simple packages usually only need a single MD file for documentation. For example, packages that contain only samples or tests that require a minimal explanation. For single-file documentation, use the package name as the filename with the MD extension. For example, if your package is named **com.unity.small-package**, name your documentation file *com.unity.small-package.md*.
If you are providing a package that contains a lot of tools, or requires a lot of explanation, you probably need to create more than one page of documentation. Multiple-page documentation provides a lot of information with a sidebar Table of Contents (TOC) where readers can easily see and understand the structure.
## How to use these guides
This documentation set itself is an example of how to set up more complex documentation with multiple pages organized with a Table of Contents (TOC). However, you can also use these pages as guides for how to create single-page documentation:
* [tools-package-guide.md](tools-package-guide.md) for a package that includes features that augment the Unity Editor or Runtime (modules, tools, and libraries)
* [sample-package-guide.md](sample-package-guide.md) for a package that includes sample files
* [test-package-guide.md](test-package-guide.md) for a package that provides tests
> **Tip**: You can also use the single-page guides to help create more complex documentation: start with one big MD file and then split it out later when you are happy with the structure.
>
> Alternatively, you can create the overall structure in the *TableOfContents.md* file and then create the individual MD files as you go along. For more information on using multi-page documentation, see the Confluence page [Using TOCs with multiple MD files](https://confluence.hq.unity3d.com/display/DOCS/Package+documentation+with+Git#PackagedocumentationwithGit-UsingTOCswithmultipleMDfiles).
The guide pages contain some example text to get you started, along with some instructions displayed as **Notes**. In addition, there are a few real-world examples displayed *in italics* which are there for reference only. Delete all of the instructions and examples, and then remove any other sections or text you don't need.
When you want to review the overall structure or test how the documentation will look online, use the Package Manager's **DocTools** extension. For more information, see the instructions on Confluence for [installing the DocTools package](https://confluence.hq.unity3d.com/display/DOCS/Package+documentation+with+Git#PackagedocumentationwithGit-InstallingDocTools). Then open your package in the Package Manager and click the **Generate Documentation** button. DocFx generates a version using your localserver.
### Markdown for single vs. multiple MD files
If you are creating a single MD file for your documentation, you can use a Heading 1 section to add more topics. Use the **#** character followed by your title:
```markdown
# Heading 1 section
Here are the contents of your main topic.
```
If you need to split a main topic into smaller subtopics, use a Heading 2 section:
```markdown
## Heading 2 section
Here are the contents of your subtopic.
```
If you are creating documentation with a Table of Contents and multiple MD files, you can put each main topic in its own page. Other than that, you can use virtually the same markdown. The only real difference is when creating links.
### Links to other topics
If you want to link to a specific topic, add an anchor (bookmark) just before the heading:
```markdown
<a name="anchorID"></a>
# Heading 1 section
Here are the contents of your main topic.
```
> **Note**: Anchor links must be unique inside an MD file.
If the topic you are linking to is defined in the same file as the link, add a markdown link to the anchorID you used:
```markdown
...
And here is the text where the [link](#anchorID) appears.
...
<a name="anchorID"></a>
# Heading 1 section
Here are the contents of your main topic.
```
If the topic you are linking to is defined in a different file from the link, use the name of the page first:
```markdown
This is what an [external link](anotherfile.md#anchorID) looks like.
```
If you are linking to a topic that comes first in another file, you can just use the name of the page on its own:
```markdown
This is what a [link to another page](anotherfile.md) looks like.
```
Notice that in both cases, you have to specify the `.md` extension in the link text.
### Images
If you have topics that include screen grabs or diagrams, add a link to the image after the paragraph with the instruction or description that references the image. In addition, a caption should be added to the image link that includes the name of the screen or diagram. All images must be PNG files with underscores for spaces. No animated GIFs.
Here is an example of how to present a screen grab:
![A cinematic in the Timeline Editor window.](images/example.png)
Notice that the example screen shot is included in the images folder. All screen grabs and/or diagrams must be added and referenced from the images folder.
For information and guidance on creating and adding screen grabs, see [the Unity documentation standards](https://unity-docs.gitbook.io/style-guide/format/images/screenshots).
## Structuring the information
Most people need some orientation so they can understand what the purpose of the package is and what it contains, along with any important warnings or general information. This high-level information should appear in the [First page or section](#initial).
After providing this preliminary information, you can provide sections that contain:
* An overview of the user interface (if it's complicated)
* Directory listings (for samples)
* More in-depth workflows
* More advanced topics.
* Reference pages should appear near the end.
* Any tutorials you may want to provide should also be at the end.
> **Tip:** For guidance on good writing practices, Unity documentation standards, and style guidelines, see the [Unity Docs Style Guide](https://unity-docs.gitbook.io/style-guide/).
<a name="initial"></a>
### First page or section
The initial section of the documentation should contain this information:
| **Subsection** | **Instructions/Description** |
| ------------------------- | ------------------------------------------------------------ |
| **Title** and introduction | The title of the package (for example, **About MyPackage**).<br /><br />After the title of the package, you should give a very brief overview of what the package does and what it contains. |
| **Preview package** | Following the introduction, add the **Preview package** section. The guides provide some boilerplate text that you can use as-is. <br /><br />**Note:** Most of the time, when you are documenting a package, it is either in development or in a pre-release (preview) phase. However, once your package is verified for a Unity version, it's important to remember to remove this section. |
| **Package contents** | This section includes the location of important files you want the user to know about. For example, if this is a sample package containing textures, models, and materials separated by sample groups, you may want to provide the folder location of each group. |
| **Installation** | Include instructions for installing the package. For most of the installation procedure, you can refer to the Packages documentation for [installing packages](https://docs.unity3d.com/Manual/upm-ui-install.html) in the Unity user manual. However, you should also provide any additional instructions to help the user complete the setup. |
| **Requirements** | [Optional] If your package requires anything other than the standard Unity system requirements, add this section. |
| **Known limitations** | [Optional] If your package has unresolved issues or limitations, enumerate them in this section. |
| **Helpful links** | [Optional] You can use this section to provide links for getting help and providing feedback, such as public forums or knowledge bases, helpdesk contacts, tutorials, and more. |
### Subsequent pages or sections
These are the suggested main topics you can add to your documentation after the first page or section:
| **Section** | **Instructions/Description** |
| -------------------------------------------------- | ------------------------------------------------------------ |
| **Using &lt;package-name&gt;** | For packages that augment the Unity Editor with additional features, this section should include a high-level workflow. If there is more workflow, or it you need to provide more detail, consider adding a **Workflows** section. <br /><br />You can also include some information about your UI if your package implements a dialog, window, or component. If you have more than one set of properties or UI to document, consider adding a **Reference** section.<br /><br />For packages that include test or sample files, this section may include detailed information on how the user can use these in their Projects and Scenes. You can also include workflow diagrams or illustrations if it helps explain how to use your tests or samples. <br /><br />If this section begins to get really large, you can either divide it into smaller subsections or move some of the information to a new topic, including the **Workflows**, **Advanced topics**, or **Reference** sections. |
| [Workflows](tools-package-guide.md#Workflows) | [Optional] <br />This is where you can describe typical ways to use the tools, modules, libraries, etc. A workflow is a simple set of steps that the user can easily follow. Workflows demonstrate how to use the feature.<br /><br />Provide a list of steps containing screen grabs to better illustrate how to use the feature, and links to the [more advanced topics](#Advanced) or any [reference pages](#Reference). |
| [Advanced topics](tools-package-guide.md#Advanced) | [Optional] <br />This is where you can provide detailed information about what you are providing to users. This is ideal if you don't want to overwhelm the user with too much information up front. You can link to topics by dropping an anchor (`<a name="AnchorID"></a>`) near the topic target and then creating an MD link with that anchor ID (`[display text for the link](#AnchorID)`) from another section.<br /><br />If you have a lot of advanced topics, you can create subsections and display a list of links to each one so your readers can easily find what they are looking for. |
| [Reference](tools-package-guide.md#Reference) | [Optional] <br />If you have user interace with a lot of properties, you can provide the details in a reference section. Use tables, if possible, to describe properties. Reference tables should have two columns with the bolded name of the property on the left and the description of how to use it on the right.test-package-guide.md#reference) |
| [Tutorials](tools-package-guide.md#Tutorials) | [Optional] <br />If you want to provide walkthroughs for complicated procedures, you can also add them here. |
> **Remember**: You don't have to stick to these exact sections. You can define your own topics, as long as you generally follow these principles:
>
> * Provide some high-level information up front to orient your users.
> * Provide the low-level information (such as properties reference and tutorials) at the end.
> * Provide the rest of the information in a series of topics in the middle. Depending on the complexity of your package, you might only have one topic after the introduction, or you might have several topics with sub-topics.
> * Provide links to separate topics and sections that are related to give the user the fullest picture possible.

Просмотреть файл

@ -1,43 +0,0 @@
# About &lt;package name&gt; samples
The &lt;package name&gt; package includes samples of &lt;name of Asset type, Model, Prefabs, and/or other GameObjects in the package&gt;. For more information, see &lt;xref to topic in the Unity Manual&gt;.
> **Note**: Here is an example for reference only. Do not include it in the final documentation file.
> *The Timeline Examples package includes examples of Timeline Assets, Timeline Instances, animation, GameObjects, and scripts that illustrate how to use Unity's Timeline. For more information, see Unity's Timeline in the Unity Manual. For licensing and usage, see Package Licensing.*
## Preview package
This package is available as a preview, so it is not ready for production use. The features and documentation in this package might change before it is verified for release.
>**Note**: For packages in preview or development, include the **Preview package** section, but remember to remove it completely when the package is verified.
## Package contents
The following table describes the package folder structure:
|**Location**|**Description**|
|---|---|
|*MyFolderName*|Contains &lt;describe what the folder contains&gt;.|
|*MyFolderName/MyFileName*|Contains &lt;describe what the file represents or implements&gt;.|
<a name="Installation"></a>
## Installation
To install this package, follow the instructions in the [Package Manager documentation](https://docs.unity3d.com/Manual/upm-ui-install.html).
>**Note**: This section begins with a cross-reference to the official Unity Manual topic on how to install packages. If the package requires special installation instructions, include these steps below:
Once installed, you can click the **Import to project** button in the Package Manager to import each of the following samples:
- **&lt;name of sample 1&gt;**: The new sample folder appears &lt;at this location&gt;.
- ... etc.
<a name="UsingPackageName"></a>
# Using &lt;package name&gt;
To use the &lt;sample-name&gt;, make sure you have already [imported the sample](#Installation) into your Project. Then you can ...

Просмотреть файл

@ -1,38 +0,0 @@
# About the &lt;package name&gt; tests
The &lt;package name&gt; package provides a test suite for the &lt;feature or package name&gt;.
## Preview package
This package is available as a preview, so it is not ready for production use. The features and documentation in this package might change before it is verified for release.
>**Note**: For packages in preview or development, include the **Preview package** section, but remember to remove it completely when the package is verified.
## Package contents
The following table describes the package folder structure:
|**Location**|**Description**|
|---|---|
|*MyFolderName*|Contains &lt;describe what the folder contains&gt;.|
|*MyFolderName/MyFileName*|Contains &lt;describe what the file represents or implements&gt;.|
<a name="Installation"></a>
## Installation
To install this package, follow the instructions in the [Package Manager documentation](https://docs.unity3d.com/Manual/upm-ui-install.html).
>**Note**: This section begins with a cross-reference to the official Unity Manual topic on how to install packages. If the package requires special installation instructions, include these steps below:
In addition, you need to install the following resources:
- **&lt;name of resource 1&gt;**: To install, open **Window** > **&lt;name of menu item&gt;**.
- ... etc.
# Running the tests
To use the &lt;test-name&gt;, make sure you have ...

Просмотреть файл

@ -1,196 +0,0 @@
# About &lt;package name&gt;
Use the &lt;package name&gt; package to &lt;list of the main uses for the package&gt;. For example, you can use &lt;package name&gt; to create/generate/extend/capture &lt;mention major use case, or a good example of what the package can be used for&gt;.
The &lt;package name&gt; package also includes &lt;other relevant features or uses&gt;.
> **Note**: Here are some examples for reference only. Do not include these in the final documentation file.
> *Use the Unity Recorder package to capture and save in-game data. For example, use Unity Recorder to record an mp4 file during a game session. The Unity Recorder package also includes an interface for setting-up and triggering recording sessions.*
> *AR Foundation allows you to work with augmented reality platforms in a multi-platform way within Unity.*
>
> *AR Foundation is a set of `MonoBehaviour`s and APIs for dealing with devices that support the following concepts:*
>
>* *World tracking: track the device's position and orientation in physical space.*
>* *Plane detection: detect horizontal and vertical surfaces.*
>* *Point clouds, also known as feature points.*
>* ... *etc.*
## Preview package
This package is available as a preview, so it is not ready for production use. The features and documentation in this package might change before it is verified for release.
>**Note**: For packages in preview or development, include the **Preview package** section, but remember to remove it completely when the package is verified.
## Package contents
The following table describes the package folder structure:
|**Location**|**Description**|
|---|---|
|*MyFolderName*|Contains &lt;describe what the folder contains&gt;.|
|*MyFolderName/MyFileName*|Contains &lt;describe what the file represents or implements&gt;.|
<a name="Installation"></a>
## Installation
To install this package, follow the instructions in the [Package Manager documentation](https://docs.unity3d.com/Manual/upm-ui-install.html).
>**Note**: This section begins with a cross-reference to the official Unity Manual topic on how to install packages. If the package requires special installation instructions, include these steps below:
In addition, you need to install the following resources:
- **&lt;name of resource 1&gt;**: To install, open **Window** > **&lt;name of menu item&gt;**.
The resource appears &lt;at this location&gt;.
- ... etc.
## Requirements
This version of &lt;package name&gt; is compatible with the following versions of the Unity Editor:
* 2018.1 and later (recommended)
>**Note**: You may also include additional requirements or recommendations for 3rd party software or hardware. If you need to include references to non-Unity products, make sure you refer to these products correctly and that all references include the proper copyright (&copy;), trademark (&trade;) or registered trademark(&reg;):
To use this package, you must have the following 3rd party products:
* &lt;product name and version&gt;&trade;
* ...etc.
## Known limitations
&lt;package name&gt; version &lt;package version&gt; includes the following known limitations:
* &lt;brief one-line description of limitation.&gt;
* ... etc.
>**Note**: If there are no known limitations, or if the limitations are trivial, exclude this section.
>
>Here is an example for reference only. Do not include this in the final documentation file:
---
*The Unity Recorder version 1.0 has the following limitations:*
* *The Unity Recorder does not support sound.*
* *The Recorder window and Recorder properties are not available in standalone Players.*
* *MP4 encoding is only available on Windows.*
---
## Helpful links
If you are new to &lt;package-name&gt;, or have a question after reading the documentation, you can:
* Watch the [Tutorials](https://www.youtube.com/playlist?list=PLAYLIST-ID) here.
* Join our [support forum](https://forum.unity.com/forums/FORUM-ID/).
* Follow us on [Twitter](http://www.twitter.com/TWITTER-ID).
<a name="UsingPackageName"></a>
# Using &lt;package name&gt;
To use the &lt;tool-name&gt;, attach this component to your GameObject and open the &lt;component-name&gt; in the Inspector:
`![The XXX component](images/LOCATION-OF-SCREENGRAB)`
Use this component to access the YYY and ZZZ properties which control ...
> **Note**: For a package containing a library, you can use this type of a description:
The XXX and YYY libraries contain APIs which allow you to &lt;do-something&gt;. The &lt;class-name&gt; class extends the &lt;other-class-name&gt; class so you can ...
You can implement a &lt;something&gt; using the XXX:
```C#
using Unity.Editor;
using MyPackage;
namespace MyNamespace
{
public class MyClass
{
...
}
}
```
<a name="Workflows"></a>
# &lt;package name&gt; workflows
To edit objects and elements:
1. Decide which tools can help you achieve the end results. There might be multiple solutions that can all produce the effect you want.
2. Select the element(s) that you want to modify. Often, the editing tool impacts which elements you need to select and how you need to select them.
3. Depending on which tool you are using, set any options to help customize the outcome or change the default settings.
4. Perform the action. Depending on what you are doing, this may be a simple matter of clicking a button. In some cases, you may be carrying out some intricate procedures. For example, you can click to ...
<a name="Advanced"></a>
# Advanced topics
This section provides more information on the following topics:
* [First topic](#first): provides a list of ...
* [Second topic](#second): explains the origin of ...
* etc.
<a name="first"></a>
## First topic
This is a list of ...
<a name="second"></a>
## Second topic
The XXX extends the YYY by tracking the ...
<a name="Reference"></a>
# XXX window
You can access these properties on the XXX window:
| **Property:** | **Function:** |
|:--- |:--- |
| __MySlider__ | Set this value to ... |
| __MyCheckbox__ | Enable this property to ... |
| __MyDropdownMenu__ | Choose how you want to ... |
| &nbsp;&nbsp;&nbsp;&nbsp; Value 1 | Select this value if ... This is the default. |
| &nbsp;&nbsp;&nbsp;&nbsp; Value 2 | Select this value if ... |
| &nbsp;&nbsp;&nbsp;&nbsp; Value 3 | Select this value if ... |
| __MyReference__ | Set a reference to ... |
<a name="Tutorials"></a>
# Tutorials
This tutorial demonstrates how to XXX by &lt;doing something&gt;:
1. Do the first task.
2. Do the second task. The following image appears:
![A cinematic in the Timeline Editor window.](images/example.png)
4. etc ...

Просмотреть файл

@ -3,7 +3,7 @@ An XR-Optimized line renderer that is also capable of producing very inexpensive
## Setup and usage
1. Place the XRLineRenderer folder into Assets\XR Utilities\XRLineRenderer in your project.
1. Import the XRLineRenderer package in your project.
2. Add a XRLineRenderer or XRTrailRenderer component to your gameobject. The interface is nearly identical to the built in Unity Line and Trail Renderers.

Просмотреть файл

@ -1,5 +1,5 @@
{
"name": "Tests.xrlinerenderer_Tests",
"name": "Unity.Labs.XRLineRenderer.Tests",
"optionalUnityReferences": [
"TestAssemblies"
]

Просмотреть файл

@ -1,5 +1,5 @@
fileFormatVersion: 2
guid: 79990593560724bb8b39e8ee14ced7cb
guid: 4b435ccf8bd6a473a97f57e603de1b23
AssemblyDefinitionImporter:
externalObjects: {}
userData:

Просмотреть файл

@ -6,11 +6,11 @@ using UnityEngine.TestTools;
namespace Tests
{
public class xrlinrendererTests
public class XRLineRendererTests
{
// A Test behaves as an ordinary method
[Test]
public void xrlinrendererTestsSimplePasses()
public void XRLineRendererTestsSimplePasses()
{
// Use the Assert class to test conditions
}
@ -18,7 +18,7 @@ namespace Tests
// A UnityTest behaves like a coroutine in Play Mode. In Edit Mode you can use
// `yield return null;` to skip a frame.
[UnityTest]
public IEnumerator xrlinrendererTestsWithEnumeratorPasses()
public IEnumerator XRLineRendererTestsWithEnumeratorPasses()
{
// Use the Assert class to test conditions.
// Use yield to skip a frame.

Просмотреть файл

@ -1,7 +1,7 @@
{
"name": "com.unity.labs.xrlinerenderer",
"displayName": "XR Line Renderer",
"version": "0.1.0-preview.1",
"version": "0.1.1-preview",
"unity": "2019.1",
"unityRelease": "14f1",
"description": "An XR-Optimized line renderer that is also capable of producing very inexpensive glow effects. The XRLineRenderer mimics rendering with 3d capsules while only using two quads worth of geometry."