Github Repository best practices
This section contains a set of best practices that you can optionally follow in laying out your sample that will result in the least amount of work for you and the best experience for others in finding and using your sample.
Contributing the entire repository as a sample
SX can support an entire repository being a sample. To do this, simply select the root of the repository in the contribution UI. All files in the repo are treated as a part of the sample and any future modifications will be picked up automatically.
NOTE: Please consider whether or not the repository does in fact contain different samples that expose different features. In this case, creating multiple samples and selecting different subsets of the repository might be better since it will then enable more granular discovery of your samples. (SX does create pages and infrastructure to help Google index samples better, so more samples will help this)
Selecting a subset of repository files as a sample
SX allows selecting child folders as well as individual files within a repository.
In the case of a sample that has multiple files, it is typically best to select
folders when adding the sample. If you do this, then all content under that
folder will be included in the sample. That means if you add new files in the
future (or delete existing files) on Github, SX will be able to pick up the
changes accordingly.
In the case of samples with shared utility code, you can select the sample as well as any other code in the project that you wish to be included in the sample.
NOTE: currently when you click to "Download" a sample in SX, Github services are used to create a zip of the sample. Github does not support being able to specify a subset of repo files when creating a zip. As a result, a download of a given sample will include all content in the repo. (the flip side is that this may in fact be best depending on the structure of your samples and their dependencies)
How to use a README file for your sample description
Sample Exchange allows you to manually type HTML description text, and then optionally append any number of README.md files (markdown files that we translate in the backend to HTML) to this description. This allows a number of use cases including the ability to maintain all description content in the sample itself on Github. You can then use any syntax Github supports in the README.md file such as having inline images located in your repo.
To do this, explicitly select one or more README.md file(s) or a folder containing README.md file(s) as a part of your sample. You an optionally manually type text in the description edit box if you wish but this is not required. Below the description edit box you will see an "Append Readme" section. Check the boxes next to the README.md files that you would like to append to your samples description. Sample Exchange will automatically pick up any changes to your selected sample files including these README.md files.
Note that technically we support README*.md, so if you have multiple samples in the same directory you should still be able to maintain the description in individual README files. (e.g. "README Sample number one.md", "README_My_Other_Sample.md" would work)
Embedding images in your sample description
In order to embed images in your sample description, you must use a README.md as your sample description. In that README.md you can do anything that Github supports as syntax. For images you can have an absolute http link to the image (which means you need to host it somewhere, though that somewhere can even be in another github repo via raw links), or you can have a relative link in your repository to the image, which is arguable the best approach since the image is then versioned with the same.
Markdown syntax to have an inline image:
![alternate text](relative/path/to/my/image.png]
Embedding Metadata in your source files
SX parses your source files when you contribute them as samples in an attempt to heuristically determine sensible defaults for metadata like name, description, programming language, etc. You probably have comments in your sample anyway, so why not follow a convention and save yourself some typing?
See Sample Metadata Conventions for different coding conventions that you can leverage to provide a name and description for your sample without having to type it in.
Associating a sample with an API
Samples support the concept of text tags. If you create a tag with the exact name of the API on the sample, that sample will magically show up as being associated with the API in API Explorer. For example for https://code.vmware.com/apis/191/vsphere-automation the name of the API is "vSphere Automation API". Adding a tag with this exact text will cause it to show up in API Explorer.