Code Monkey home page Code Monkey logo

vellum-client-generator's Introduction

Vellum API & Docs

Tagging a release on this repository will update the following clients:

What is in this repository?

This repository contains

  • Vellum's Fern API Definition which lives in the definition folder
  • Generators (see generators.yml)
  • Definition for Help Documentation

What is in the API Definition?

The API Definition contains an OpenAPI Specification adapted to be compatible with Fern.

To make sure that the definition is valid, you can use the Fern CLI.

npm install -g fern-api # Installs CLI
fern check # Checks if the definition is valid

What are generators?

Generators read in your API Definition and output artifacts (e.g. the TypeScript SDK Generator) and are tracked in generators.yml.

To trigger the generators run:

# output generated files locally
fern generate

# publish generated files
fern generate --group publish --version <version>

The publish command currently runs in a GitHub workflow (see ci.yml)

Publishing new client versions

Here are the steps required to publish a new version of our API clients.

  1. cd into the django directory from within the main vellum repo
  2. Run make generate-swagger-all
  3. Open the generated schema_api_client_v1.yaml file
  4. Copy the contents of the file and paste it into the definition within this repo: fern/openapi/openapi.yaml
  5. Optionally run fern check to make sure all is good.
  6. Optionally run fern generate to see the newly generated clients locally.
    • If this is your first time, fern will ask you to log in. Hit Y to proceed logging in through GitHub.
  7. Commit and push the changes to a new branch an open a PR
  8. Upon approval by at least one other reviewer, merge the branch into main.
  9. Create a new Release within Github. This will trigger a github action that will publish the new clients to their respective repos.

Upgrading Fern

You can use the following command to upgrade fern to the latest version:

fern upgrade --rc

Docs Site

Fern hosts our docs site at https://docs.vellum.ai/. The site navigation and page structure is defined by the docs.yml file. The content for each page is defined in the help folder as .mdx files using markdown syntax.

Best Practices for Writing Docs

See here for best practices when writing customer-facing product docs. These guidelines apply to help docs, change log items, and more.

In addition to those guidelines, you should also strive to:

  1. Ensure each page defines title, description, and image properties. This is important for SEO and social sharing.
  2. Embed Loom videos as iframes. Update the video's title directly in Loom.

Static Assets

Fern is in the process of adding support for relative links to static assets like images. In the meantime, we host all images ourselves in this public GCS bucket.

Custom Components

You'll notice the usage of some custom components like CodeBlock. These are specific to fern. Docs for available custom components can be found here.

Local Development

Fern has not yet released a mechanism to locally compile and preview the docs site. Instead, you have two options:

  1. Deploy to a shared staging site by following the steps below; or
  2. Open a PR. There's automation that'll comment with each new commit and include a link to a publicly visible preview site.

Deploying Docs to Staging

You can publish the docs to our shared staging site by running the following command:

fern generate --docs --instance vellum-staging.docs.buildwithfern.com

The staging site can be found at vellum-staging.docs.buildwithfern.com.

Deploying Docs to Production

Deployment to production happens manually with each merge to main that results in a diff to the docs. If for some reason you need to deploy docs manually, you can run:

fern generate --docs --instance vellum.docs.buildwithfern.com

The production site can be found at docs.vellum.ai.

Troubleshooting

If you run into errors, you can add the --log-level debug flag to get more information.

If you get a 403 error, you may need to first run fern login. You might also need to be added to the Vellum org in Fern, which requires contacting the fern team in #fern-x-vellum in Slack.

vellum-client-generator's People

Contributors

amckinney avatar anitakirkovska avatar armandobelardo avatar ashleeradka avatar dannysheridan avatar dsinghvi avatar dvargas92495 avatar jacksonhardy avatar kafkas avatar m-abboud avatar nihalathanikkal avatar noanflaherty avatar peicodes avatar siddseethepalli avatar teisjayaswal avatar zachkirsch avatar

Stargazers

 avatar  avatar  avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.