Organization

Substrate documentation consists of API docs, user docs, and developer docs.

The API docs simply uses cargo doc to generate docs for the root cargo workspace as static HTML.

The user docs and developer docs are Docusaurus docs. The Docusaurus website is configured using docusaurus.config.ts and site-config.json. The behavior of the website differs depending on whether the branch key in site-config.json is main or a different branch:

• On the main branch, the blog is present and release documentation is available.
• On other branches, only documentation corresponding to the latest code is available.

The site-config.json should not be modified in the code base, but is automatically updated when deploying docs from a branch.

User docs are versioned, while developer docs are not. To make it easier to reference correctly-versioned files, the docusaurus.config.ts provides several global variables:

docusaurus.config.ts

let vars = [
  ["VERSION", version],
  ["EXAMPLES", getExamplesPath(version)],
  ["API", getApiDocsUrl(version)],
  ["GITHUB_URL", getGitHubUrl(siteConfig.branch)],
];

In the user docs, code snippets should always reference code in the appropriately-versioned examples/* folder. This can be done using the EXAMPLES global variable:

import CodeSnippet from "@site/src/components/CodeSnippet";
export const inverterMod = require(
  `{{EXAMPLES}}/sky130_inverter/src/lib.rs?snippet`,
);

<CodeSnippet language="rust" title="src/lib.rs" snippet="imports">
  {inverterMod}
</CodeSnippet>;

The developer docs should always reference the latest code. All of the global variables will reference the correctly-versioned docs when referenced in the developer docs. The following can be used to reference the actual code base:

import CodeSnippet from "@site/src/components/CodeSnippet";
export const context = require(`@substrate/substrate/src/context.rs?snippet`);

<CodeSnippet language="rust" title="substrate/src/context.rs" snippet="context">
  {context}
</CodeSnippet>;

The resulting code snippet would look like this:

substrate/src/context.rs

/// The global context.
///
/// Stores configuration such as the PDK and tool plugins to use during generation.
///
/// Cheaply clonable.
#[derive(Clone)]
pub struct Context {
    pub(crate) inner: Arc<RwLock<ContextInner>>,
    installations: Arc<HashMap<TypeId, Arc<dyn Any + Send + Sync>>>,
    /// The executor to which commands should be submitted.
    pub executor: Arc<dyn Executor>,
    /// A cache for storing the results of expensive computations.
    pub cache: Cache,
}