Visual Studio Code–the Code Tours extension for in context and interactive readme

Lucas Jellema

The most popular IDE – VS Code – comes with a ton of extensions, and each can make life easier, more productive and more fun for developers. Recently I came across the Code Tours extension. An extension that supports the creation of guided tours through the files in your VS Code workspace.image

A Code Tour consists of a series of descriptive steps – defined using markdown with rich formatting including code snippets, URL references, file links and images – and associated with specific locations in your sources.

image

A tour can guide a fellow developer through the sources much better and more pleasantly than any readme document could ever do. Using Code Tours, you can create very accessible:

  • explanations of involved flows through the code
  • analysis of bugs to be resolved
  • overviews of the changes created as part of a PR
  • descriptions of dependencies between multiple files
  • reading instructions across multiple sections in multiple documents
  • overviews of solution designs for new features and user stories
  • hands on instructions for a workshop or training

To get going with Code Tours:

  • Install the Code Tours extension in VS Code

    image
  • Start recording a new Tour (for the current project)image
  • Add Code Tour Steps in the relevant locations in your sources

    image

    The code tour is defined in a JSON document included in the project. You can edit that JSON document. It is included with the sources when the files are pushed to a Git repo. The Code Tour can also be exported and imported in a different VS Code instance – to allow sharing without having to push to a repo.
  • You can start your tour through a code base from the Code Tour pane and from any Code Tour Point of Interest in the code base

    image

Here is an example of a code step that uses from of the layout options:

image

Using vscode.dev it is easy to share an example of a code base with some Code Tours. Navigate to this URL https://vscode.dev/github.com/lucasjellema/cloudnative-on-oci-2021 that is composed of vscode.dev and the URL for a GitHub repository. What this URL will do is launch vscode.dev (Visual Code in the browser) and load the code in that repository.

image

If you open the CodeTour pane, you will encounter several Code Tours. Run them to see the effected of being taken by the hand and shown around a code base.

image

Resources

VS Code Tours Extension https://github.com/microsoft/codetour

YouTube – VS Code tips — The CodeTour extension – https://www.youtube.com/watch?v=cUoYQKZPZcg

Tobias Timm – On board your code base with CodeTour – https://dev.to/tobiastimm/onboard-your-codebase-with-codetour-2jc8

My GitHub Repository with a Tour Guided Code Base: https://github.com/lucasjellema/cloudnative-on-oci-2021

Inspect that same code base in browser based VS Code : https://vscode.dev/github.com/lucasjellema/cloudnative-on-oci-2021

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Next Post

Creating, Building and Invoking a Function on OCI with Terraform

Automation through infrastructure as code is the name of the game. And I am a player in that game. In the last few weeks I have spent a lot of time on creating resources on Oracle Cloud Infrastructure. Through the console, using Terraform and the Resource Manager and Stacks, with […]
%d bloggers like this: