Plan for migrating VS Code API docs

[octref]

Following microsoft/vscode#58226 and internal discussions, we decided to move the existing extension docs (Extension Authoring & Extensibility Reference) from /docs to its own place, /api. You can preview it at https://vscode-ext-docs.azurewebsites.net/api.

This plan captures the migration. We plan to publish a minimal version by the end of October iteration, and continue to improve it in the following months.

Iconography

• 🌟 Nice-to-have items. These items would make the whole extensibility doc more complete, but are not necessary for publishing.
• 📝 Items that require writing new docs.
• 📄 Link to file.

Working On The Items

• Work happen in the ext-docs branch of vscode-docs
• CI automatically builds ext-docs branch and publish it to https://vscode-ext-docs.azurewebsites.net/ for preview
• Each item links to its corresponding markdown files. Each file has some writing instructions. Work on that file, push changes to ext-docs branch and check the results on https://vscode-ext-docs.azurewebsites.net.
• Links: Link to end points on the preview site. We'll do a find-replace for the domain name before publishing.
• Image/Gif: They follow the same folder convention as other parts of the website.
  • If you have /foo/bar/topic.md
  • Create a folder /foo/bar/images/topic/, and put images in it
  • In the MD file, link the file with ![](images/topic/<my-image>.png)
  • A sample change: 98022a9
• Finally, remove the old documents/images. Endpoints to them will be redirected.

Write and Review key topics

Each topic has two assignees, for example A / B. A writes the doc and B reviews it.
This part tracks the writing. Reviewing assignment will be created as testplan items.

• 📝 Overview 📄 @octref (review: @jrieken)
• 📝 Extension Capabilities / Overview 📄 @mjbvz (review: @jrieken)
• 🌟📝 Extension Capabilities / Theming 📄 @octref (review: @bpasero)
• 🌟📝 Extension Capabilities / Extending Workbench 📄 @isidorn (review: @sandy081)
• 📝 Extension Guides / Overview 📄 @octref (review: @sandy081)
• 📝 Language Extensions / Overview 📄 @octref (review: @dbaeumer)

Hello Code

@auchenberg @octref

Hello Code is the HelloWorld sample in VS Code API land. This example is a cornerstone in the new API doc. It should:

• Explain the lifecycle of scaffold / write / run / debug / test / publish extensions
• Explain the fundamental concepts, such as contribution points, how to use VS Code API
• Point people to correct tools and resources. For example, vscode NPM module, vsce for packaging and publishing, yo code for scaffolding.

---

• Define subtopics and their contents @octref & @auchenberg
• 🏃 Put into Hello World section existing docs from Hello World, Word Count, Developing / Testing / Publishing and make them a coherent piece 📄 @octref @auchenberg
• Publish the sample code as hellocode-sample at https://github.com/Microsoft/vscode-extension-samples @octref

Extension Guides

Each assignee should:

• Move existing docs to the new place and do some editing.
• Update the sample to meet the sample quality standard. Plan for normalizing samples vscode-extension-samples#110.

---

• Color Theme 📄 @bpasero
• Task Provider 📄 @dbaeumer
• Webview 📄 @mjbvz
• 🌟📝TreeView 📄 @sandy081
• Debugger 📄 @weinand
• Source Control API 📄 @joaomoreno
• Markdown Extension API 📄 @mjbvz

References

@octref will do the moving.

• vscode API
• Principle and Patterns
• Contribution Point
• Activation Event
• Theme Color Reference
• Document Selector
• Complex Commands

Language Extensions

• Migrate Language Extension Guidelines 📄 @octref
• Split original Themes, Snippets and Colorizers into Syntax Highlighting (📄) and Snippets (📄) topics @octref (moving) / @jrieken (reviewing)
• Migrate Language Server Example 📄 and 📄 @octref

[lannonbr]

The groundwork that has been done so far looks extremely promising. I think it will be great to have a more in-depth look at the API for existing devs as well as being welcoming to new devs.

Glad to see the work being done with this @octref!

[gregvanl]

Assigned to Pine so there is an owner

[octref]

Closed in favor of #2199.