tilt-dev / tilt.build

Tilt landing page

tilt.build

Tilt landing page, docs page, and blog page

• https://tilt.dev/
• https://docs.tilt.dev/
• https://blog.tilt.dev/

Developing

0. Install yarn

1. Install Tilt

2. Run tilt up

The landing page will be running at http://localhost:4000/.

The docs page will be running at http://localhost:4001/.

The blog page will be running at http://localhost:4002/.

Edits to the markdown will auto-update the HTML. The landing page lives under src and the docs page lives under docs. The docs directory has symlinks to share stuff with the landing page.

When you're finished, merge to master and Netlify will auto-deploy the site.

API docs

The API docs are a little bit more complicated.

We write the API docs as docstrings in Python files in the main Tilt repo. Then, during the release pipeline (release-update-tilt-docs.sh), the files are generated and updated here (under api/api), Sphinx generates HTML fragments (make api), and then Jekyll serves that HTML fragment.

The autogenerated API Python files include instructions on how to edit the source content.

License

Copyright 2022 Docker, Inc.

Licensed under the Apache License, Version 2.0

tilt.build's Issues

missing API docs for readiness_probe

local_resource(readiness_probe) is documented here: https://docs.tilt.dev/local_resource.html#readiness_probe

but not here: https://docs.tilt.dev/api.html#api.local_resource

cc @milas

Add dark theme to docs https://docs.tilt.dev

Dark theme for the docs.

Currently Tilt app is dark-only and docs are light-only. It is hard to switch from one to the other, especially for people with vision issues. Please add light theme for the app and dark theme for the docs. Thank you!

tilt-dev/tilt#1813

Broken link to fast_build

https://docs.tilt.dev/api.html#api.fast_build

links to

https://docs.tilt.dev/fast_build.html

which 404s

Provide example of cleanup on tilt down

This seems to come up every so often; I couldn't find an example of it in the docs, however. It probably warrants a quick mention somewhere.

For example:

if config.tilt_subcommand == "down":
  local('./cleanup.sh')

See also: https://docs.tilt.dev/api.html#modules.config.tilt_subcommand

(There might be broader improvements/enhancements re: resource stopping we want to do independently, but given that this is a pretty common use case, having the current solution documented seems reasonable to me.)

Reorder functions to be before classes in API docs

Most users are probably using Tiltfile built-in functions a lot more than they are the classes. It'd be great to reorder them so that the functions come first. Is this possible in Sphinx?

Mention the need for specifying platform in bazel docs

See this PR for context

Scrolling gets stuck on iOS Safari

Chris Dary on Twitter reports:

just fyi y’all need to fix the scrolling in iOS safari for your marketing site. It gets stuck unless you pinch zoom out first

docs: Wrong error level in the "Code. Update. Repeat." chapter of the tutorial

In the "Let’s test it out:" list, Point 3 states: "Find the logLevel line and change it from 'error' to 'info'". Although, in the source code the logLevle is set to 'warn'. So, Point 3 should read "Find the logLevel line and change it from 'warn' to 'info'".

Add More Starlark Info to Docs

It's easy to miss the fact that Tiltfiles are written in Starlark. In the guide should we have even just a one paragraph descriptor with some simple examples that demonstrate what Starlark is and how it works?

Add index/ToC for API ref

It would be super helpful if there was a more compact list of the classes/methods on the API reference page, maybe at the top or in a side bar. This would help with (a) discoverability of new methods, and (b) navigation.

Thanks!

include docs about using tilt set to override default values

Recently, I was using the option set to override default values from a helm chart. I know there are other options of how to use this. But didn't found any information related to set on the docs.

k8s_yaml(helm('./chart', name='tilt-workshop-app', namespace='default', set=['replicaCount=2']))

So, I looked at this repository to include this info but didn't found how to do it. There is some place where I can found info on how to include that or some page showing us how to contribute?

I believe this information is valuable and we should have it on the docs page.

What do you guys think?

docs: unclear points about resource readiness checks

Hi dear docs maintainers, I was reading https://docs.tilt.dev/resource_dependencies.html#adding-readiness-checks-for-startup-waiting and two prominent points made me think.

1. How is readiness defined? I think it is alluding to the Kubernetes status conditions described at https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties in other words, does Tilt look for:

   status:
     conditions:
     - type: Ready
       status: "True"
   

   The documentation does not make this clear.

2. Which type of workload objects does the Tilt look for, to check readiness? I see that the Pods are recognized (and presumably builtin workload controllers as well). However, for example:

   • does it know that it should wait for a Kubernetes Job to complete (a type that does not have a Ready condition) or,
   • how does a CRD that provides Ready condition (such as a knative Service CRD) work? do I need to opt-in explicitly as described in https://docs.tilt.dev/custom_resource.html#does-it-create-pods

I appreciate the answers. (But more importantly than answering to me, I wanted to point out that the docs do not make these points clear and I assume others wonder about similar things as they read the doc set.)

Examples/guidance for more complex shell escaping

Escaping shell commands is very tricky! Often in Starlark/Python, it means a combination of multiline (aka triple-quote ''') strings + raw strings (r"foo").

We've already got a few examples in the docs for shlex.quote: https://docs.tilt.dev/api.html#modules.shlex.quote

But we could probably stand to add a couple more for more complex cases with embedded quoting, for example.

Example version_settings constraints are incorrect

The documentation for version_settings (https://github.com/tilt-dev/tilt.build/blob/master/api/api.py#L927) specify two examples:

- `<0.13.0` - less than 0.13.0
- `>=0.12.0` - at least 0.12.0

However, the constraints feature was only introduced from version 0.13.2 (I think), so this example would not when running these tilt versions.

I propose updating the examples to:

- `<0.17.0` - less than 0.17.0
- `>=0.13.2` - at least 0.13.2

Although it doesn't quite solve the problem (as <0.17.0 could still reference a version before 0.13.2), at least the examples given don't directly state versions where this parameter would not work.

Add guidance for optimized live_update workflow with more frameworks

This was prompted by a user request to add a Python + fastapi example.

There's generally many popular frameworks for any given language, and it's likely impractical to maintain full examples for each. However, we could probably offer some guidance around common options/flags (e.g. most Python frameworks can run in a dev server mode that automatically picks up changes to code) for the most popular frameworks.

If there's a framework (not necessarily Python!) you're struggling to optimize your Tiltfile + live_update for, add a comment here with some details!

config.define_bool code example is jumbled

See here:

I think that code block is missing some new lines or something?

Upgrade installs tilt to wrong path

https://github.com/tilt-dev/tilt.build/blob/master/docs/upgrade.md

Install script conditionally checks for .local:

 if [[ ":$PATH:" == *":$HOME/.local/bin:"* ]]; then
      mv tilt "$HOME/.local/bin/tilt"

However upgrade instructions simply move the binary to /usr/local:

curl -L https://github.com/tilt-dev/tilt/releases/download/v0.14.3/tilt.0.14.3.mac.x86_64.tar.gz | tar -xzv tilt && \
  sudo mv tilt /usr/local/bin/tilt

So upgrading won't affect the version of tilt you have installed if tilt is installed in .local.

Suggest that upgrade instructions should simply encourage user to rerun install script?

docs: unclear that `link()` should be used with `links=[]`

It's not very clear that the link() method should be used with other methods' params that take Link types. Adding a small code example will make that relationship clearer.

Capturing user analytics

I read that Tilt captures analytics. Is there a way to send that data to an internal endpoint as well?
I would love to be able to use these analytics to see how our own users are using the platform.

(Apologies if this is not the correct place to ask this question - please point me to a more appropriate space in that case - thank you).

docs: unclear if/when there's a minimum tilt version needed

it's not always clear in our documentation if a user needs a minimum version of tilt to use certain api functions and arguments. if there is a certain version of tilt needed, but a user hasn't upgraded, they'll get a generic message that says something like:

Error: local_resource: unexpected keyword argument "dir"

even though the documentation says this argument exists. this could be pretty confusing or frustrating if you haven't used tilt a bunch.

• one example: the dir argument in local_resource is only supported in v0.20.8+
• another example: the labels argument in *_resource functions is only supported in v0.22.1+. (if a user does a lot of clicking around, they may see the resource grouping blog post and see the version note there.)

solutions for this could be:

• add better messaging for tiltfile error logs, encouraging a user to check for typos or update their tilt version
• add annotations or notes to the tilt api docs, saying something like "supported in v0.XX.x+"

Doc: Integrating Bazel with Tilt: `custom_build` never watch for source deps

In the Image Dependencies section here
https://docs.tilt.dev/integrating_bazel_with_tilt.html

custom_build supposed to be watching for actual files, but in the example its just labels. Probably typo or am I missing something?

Currently its is

def bazel_build(image, target):
  build_deps = str(local(BAZEL_BUILDFILES_CMD % target)).splitlines()
  watch_labels(build_deps)

  source_deps = str(local(BAZEL_SOURCES_CMD % target)).splitlines()
  source_deps_files = bazel_labels_to_files(source_deps)

  custom_build(
    image,
    BAZEL_RUN_CMD % target,
    source_deps,
    tag="image",
  )

It supposed to be

def bazel_build(image, target):
  build_deps = str(local(BAZEL_BUILDFILES_CMD % target)).splitlines()
  watch_labels(build_deps)

  source_deps = str(local(BAZEL_SOURCES_CMD % target)).splitlines()
  source_deps_files = bazel_labels_to_files(source_deps)

  custom_build(
    image,
    BAZEL_RUN_CMD % target,
    source_deps_files,
    tag="image",
  )

source_deps -> source_deps_files in custom_build

Minor issue with install instructions

The following step didn't work for me:

sudo snap install microk8s --classic && \
microk8s.enable dns && \
microk8s.enable registry

The problem is that my user wasn't in the microk8s group, so the enable commands don't work. You could change it to:

sudo snap install microk8s --classic && \
sudo microk8s.enable dns && \
sudo microk8s.enable registry

But I'm not sure that's the best solution.

docs: using multiple repos with tilt

Currently, the docs on Structuring Multiple Repos is very basic.
It would be good to improve them by e.g. showing an example.

Other questions that could/should be answered in those docs:

How do you deal with merging configs?

• when you load multiple Tiltfiles via load() what happens to variables that have been defined in both Tiltfiles?

Do you need to wrap top level function calls into a method?

docs image won't build in d4m 18.09.02

When running tilt up at 50f0b74 with docker 18.09.02, I get:

    ╎ [5/9] ADD src/Gemfile* /src/
    ╎ [6/9] ADD docs/Gemfile* /docs/
    ╎   → panic: failed to copy /src-0/Gemfile* to docs/: lstat /src: no such file or directory
goroutine 1 [running]:
main.main()
    /go/src/github.com/tonistiigi/copy/cmd/copy/main.go:57 +0x2af
    ╎ ERROR IN: [6/9] ADD docs/Gemfile* /docs/
ERROR: ImageBuild: executor failed running [copy --unpack /src-0/Gemfile* docs/]: exit code: 2

This was introduced by b9f20d8.
It repros if I change the dockerfile to

RUN mkdir /docs
ADD docs/Gemfile* /docs/
RUN mkdir -p /src
ADD src/Gemfile* /src/

(just to reduce the chance the /src in the error message is our /src

And doesn't repro if I replace

ADD docs/Gemfile*

with

ADD docs/Gemfile /docs/
ADD docs/Gemfile.lock /docs/

which, AIUI, should be exactly the same (given those are the only two files matching docs/Gemfile*

Also: docs/Gemfile* are symlinks to the same files in src. If I replace the symlinks with copies of their destinations, the problem goes away!

This all repros if I build outside of tilt w/ DOCKER_BUILDKIT=1 docker build.

Document that `.git` directory is automatically ignired in `docker_build`

@kavirajkanagaraj pointed out in #tilt that this is potentially confusing and isn't documented.

example_python "Recommended Tiltfile" link is bad

Hi,

On this page

https://github.com/windmilleng/tilt.build/blob/master/docs/example_python.md

The link "Recommended Tiltfile" on https://docs.tilt.dev/example_python.html points to https://github.com/windmilleng/tilt-example-python/tree/master/2-recommended but that link returns 404

"image" should be replaced with "build" in Docker Compose caveat

#987 added a helpful note for using docker_build() with docker-compose, but it has a small mistake:

When using Docker Compose, Tilt expects the image build to be either managed by your Docker Compose file (via the image key) OR by Tilt's :meth:docker_build, but not both.

should be:

When using Docker Compose, Tilt expects the image build to be either managed by your Docker Compose file (via the build key) OR by Tilt's :meth:docker_build, but not both.

The inline link points to the right section of the docker-compose docs so I think this was just an oversight. I was about to PR this myself but it seems a little involved to generate the HTML docs, so figured I'd at least open an issue while it's on my mind. Thanks!

How to combine multiple Tiltfiles with their own config

As the title says, we have multiple services in different repositories and want to add a Tiltfile with config in each of them. The services can be used independently.

But we also want to have one Tiltfile that can start multiple services together. If I try to include the other Tiltfiles from the main Tiltfile I get Error in config.define_bool: config.define_bool cannot be called after config.parse is called.

So how would I handle this case?

Docs for Tiltfile helpful workarounds/functions

We should describe useful tips and tricks, like how to use str on the blob created by local and how to die on the wrong cluster.

[as mentioned in Kubernetes slack]

[ported from windmilleng/tilt]

Document how to start a subset of services

From this #tilt thread it's clear that this isn't obvious to folks

update docs for Tiltfile Reference API with optional flag for local() function

The function local() now has an optional flag parameter echo_off which, if set, prevents the logging of whatever that was inside of local(). (This functionality was requested in Issue #3528 (tilt-dev/tilt#3528)

The docs needs to be updated with this info (most likely after the weekly release which will incorporate this functionality)