streamlit/docs

Source code for the Streamlit Python library documentation

Streamlit Docs

We use Next.js and Netlify to build our documentation site.

Building

To build the docs, clone this repo, install the NPM dependencies, and start the development server.

1. Set up your base environment

MacOS

# Some Apple dev tools (developer.apple.com/downloads)
$ xcode-select --install

# Install Homebrew
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install the Protobuf compiler, graphviz, database, and virtual environment
$ brew install protobuf graphviz gawk mysql mysql-client pkg-config unixodbc postgresql pre-commit

Installing Node JS and yarn

We recommend that you manage your nodejs installation with nvm. After following the instructions linked above to install nvm, use the following command to install the latest supported node version

# Install node
nvm install node

Note: Node has added Corepack which is a manager of package managers 😱. It supports yarn! You can enable it by running the following:

corepack enable

You may need to brew install corepack depending on how you installed node.

ARM based Macs

If you are running a MacOS computer running on the new chipsets (e.g. M1), you may hit some trouble installing pyodbc This can be solved by installing unixodbc and setting some flags. See this comment for help. We found that it just needs to be set once. Be sure to make sure you have the correct version of unixodbc in the commands.

Ubuntu

# Set up the Yarn repo
$ curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
$ echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

$ sudo apt-get update

# Install Pyenv for testing multiple Python versions
$ sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev \
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
xz-utils tk-dev libffi-dev liblzma-dev python-openssl mysql-client libmysqlclient-dev unixodbc-dev
$ curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash

# Install some other deps
$ sudo apt install graphviz python3-distutils pre-commit

# Install Yarn, pip, Protobuf, npm
$ sudo apt install yarn npm python-pip protobuf-compiler libgconf-2-4
# (libgconf is for our e2e tests in Cypress)

Probably not needed, but in case you want to update your Node installation:

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -

Windows

Streamlit's development setup is pretty Mac- and Linux-centric. If you're doing Streamlit development on Windows, we suggest spinning up a Linux VM (you can do this easily with VirtualBox, which is free); or working in a Linux Docker image.

Alternately, you can try using Microsoft's WSL ("Windows Subsystem for Linux"), which may work fine, or may result in you slowly dying from thousands of tiny papercuts (these steps were last tested on 2019-11-18):

• Install WSL, using the Ubuntu image from the Microsoft Store
• Make sure your WSL supports chmod/chown.
• Make sure you have pre-commit installed and it is available on your path.
• If you have Windows versions of Streamlit build dependencies installed (e.g. Python, nodejs), you may want to consider removing the Windows path from your Linux $PATH, to prevent conflicts.
  • See the WSL Release Notes for instructions on editing your wsl.conf file. You'll want to set appendWindowsPath=false.
• Follow the Ubuntu setup instructions above, with the following modifications:

# Install a Python version using pyenv with the `CONFIGURE_OPTS=--enable-shared` flag set:
$ CONFIGURE_OPTS=--enable-shared pyenv install 3.7.5 && pyenv global 3.7.5

$ python -m venv venv

2. Clone this repo:

git clone https://github.com/streamlit/docs.git
cd docs/

3. Install the NPM dependencies

make

4. Start the development server:

make up

The docs will be viewable at http://localhost:3000. Note that any time you modify the source files in the content/ folder, you'll need to refresh your browser tab to view the changes. You do not need to restart the development server.

File and folder structure

This repo follows a typical Next.js project structure. To contribute, you'll only edit Markdown files within the content/ folder.

• components/ Contains JS and MDX files.
• content/ This is where all the Markdown files live. This is the only folder you'll edit.
• lib/ Contains JS files.
• pages/ You'll never have to edit this folder. It contains JSX files that handle the complex index page, mapping of URL slugs, and rendering of Markdown pages in content/.
• public/ Contains all the images used in our docs.
• python/ Contains Python code to generate the docstrings for the API Reference.
• scripts/ Contains JS files.
• styles/ Contains CSS files for styling and layout.

Contributing

To add, edit, or delete content in our documentation, you have to modify Markdown (.md) files within folders and sub-folders in content/ :

• kb/ Contains .md files that populate the Knowledge Base.
• library/ Contains .md files that populate the Streamlit Library section.
• streamlit-cloud/Contains .md files that populate the Streamlit Community Cloud section.
• gdpr-banner.md You'll never have to edit this file.
• index.md Contains text that populates the index page.
• menu.md This is a special file containing only front matter that defines the docs Menu. You will need to add an entry on this file for each new page you create within the docs' site.

The directory structure of content/ does not matter as the files will be recursively read and will ignore the directories. However, we recommend following the directory structure to organize the files, mirroring the structure on the documentation website.

Add a new page

Do you want to add a new page to the docs?

1. First, decide which section the page should live in (Streamlit Library, Streamlit Community Cloud, or Knowledge Base).

2. Next, navigate to the relevant folder and subfolder within content/ and create a .md file whose filename mirrors the title of the page. E.g. For a page titled "Create a component", navigate to content/develop/concepts/custom-components/ and create a file named create-component.md.

Structure of the .md file

Now that you've decided where the file should live and have named the file, it's time to add your content!

File format:

Every .md file has front matter at the very top that defines the page title which appears in the browser tab bar, and the URL slug which appears after the slash in docs.streamlit.io/ and localhost:3000/.

E.g. For a page titled "Create a component" that should exist at docs.streamlit.io/develop/concepts/custom-components/create, the front matter at the top of create-component.md is:

---
title: Create a Component
slug: /develop/concepts/custom-components/create
---

Headings:

Use standard Markdown for headings (#, ##, ###)

Callouts:

To add a callout (Note, Tip, Warning, Important), enter your Markdown text within the appropriate tags (MDX functions), making sure to add a blank line after the opening tag and another before the closing tag. E.g.

<Note>

This is a **note** that links to our [website](https://docs.streamlit.io/).

</Note>

Embed code:

Enclose code within ` ` to embed it inline. E.g.

Create a header with `st.header`.

Embed code blocks like so:

    ```python
    import streamlit as st

    st.text("Hello world")
    ```

We support syntax highlighting for Python, Bash, TOML, SQL, and JSX.

Link to other pages in docs:

Use standard Markdown to link to other pages in the docs. E.g. Add an inline link to the "Create an app" page by including the slug defined in the front matter of the "Create an app" .md file:

Learn how to [Create an app](/get-started/tutorials/create-an-app).

Add images:

Store images you want to display in /public/images/. There are two ways to display images.

1. To display a single image, use regular Markdown. Make sure to start the path of your images from /images/ instead of /public/images/. E.g.:

   ![Secrets manager screenshot](/images/databases/edit-secrets.png)

2. To display multiple images on the same line, add an <Image /> tag containing the alt text and path to the image, for each image, and enclose all of them within <Flex> </Flex> tags. E.g. To display 3 images stored in /public/images/databases/ :

   <Flex>
   <Image alt="Bigquery screenshot 7" src="/images/databases/big-query-7.png" />
   <Image alt="Bigquery screenshot 8" src="/images/databases/big-query-8.png" />
   <Image alt="Bigquery screenshot 9" src="/images/databases/big-query-9.png" />
   </Flex>

Discoverability:

All it takes for a new page to be available at a URL is to create a Markdown file in the format described above, containing the title and slug in the front matter.

However, a user has to know the URL to visit the page. The page is therefore reachable but not discoverable. The next section describes how to add pages to the docs Menu so that users can find your page.

Add pages to the Menu

How do you make the page you created appear in the Menu? Edit the special markdown file content/menu.md. All it has is front matter in YAML.

Suppose you have created an "Quickstart" page that is available at docs.streamlit.io/get-started/installation/quickstart. You want to it to appear in the Menu within the "Get started" section, nested under the "Installation" page.

To do so, find the lines that define the category, url and visible properties for "Get Started" in menu.md and add three new lines below it, containing:

- category: Get Started / Installation / Quickstart
  url: /get-started/installation/quickstart
  visible: true

Important: You always need to add the entry you created in menu.md, or otherwise the build will fail. It is important because we use the structure on this page to create the breadcrumbs for each page. If you don't want the page to show up on the menu, you still need to add it, but you can set its visible property to false.

Edit an existing page

To edit an existing page:

1. Locate the .md file for the page
2. Edit the Markdown and save the file

To preview your changes, refresh your browser tab and visit the edited page!

Add a new docstring to the API Reference

Any time a new version of Streamlit is released, the docstrings stored in python/streamlit.json have to be updated by running make docstrings . This will build the necessary Docker image, and update the file with the documentation for the latest release on PyPi.

If you need to regenerate all function signatures, across all versions, delete the content in python/streamlit.json, leaving the file in place, and run make docstrings. This will systematically install each version of streamlit, and generate the necessary function signatures in streamlit.json.

Suppose a new Streamlit release includes a st.my_chart function that you want to include in the "Chart elements" section of the API Reference:

1. Run make docstrings

2. Create Markdown file (my_chart.md) in content/develop/api/charts/

3. Add the following to my_chart.md:

   ---
   title: st.my_chart
   slug: /develop/api-reference/charts/st.my_chart
   ---
   
   <Autofunction function="streamlit.my_chart" />

4. Add the following under the "Chart elements" heading in content/develop/api/api-reference.md:

   1. A RefCard MDX function containing the URL slug defined in my_chart.md . This is the card that will appear on the API Reference landing page.
   2. An Image MDX function containing alt text and the location of the image to be displayed on the card.
   3. A bold heading that will appear on the card (#### Heading). It appears below the card image.
   4. A brief description of the st.my_chart . It appears below the card heading.
   5. A code block illustrating how to use st.my_chart. It appears below the card description and has a Copy icon that when clicked copies the code block to the users' clipboard.

    <RefCard href="/develop/api-reference/charts/st.my_chart">
    <Image pure alt="Tux, the Linux mascot" src="/img/data-table.png" />

    #### My charts

    Display a chart using the MyChart library.

    ```python
    st.my_chart(my_data_frame)
    ```

    </RefCard>

5. Add the following 2 new lines to menu.md so that st.my_chart appears in the Menu:

   - category: Streamlit Library / API Reference / Chart elements / st.my_chart
     url: /develop/api-reference/charts/st.my_chart

6. Save your changes and refresh the browser tab. If all went well, you should see a new entry in the Menu, a new card in the API Reference, and a new page for st.my_chart.

Add to the Knowledge Base

The Knowledge Base (KB) is divided into five sections:

1. Tutorials: Step-by-step examples of building different types of apps in Streamlit
2. Using Streamlit: Frequently asked questions about using Streamlit Library
3. Deployment Issues: Articles about deploying Streamlit apps
4. Streamlit Components: Articles about Streamlit components
5. Installing Dependencies: System and Python dependency issues while using or deploying Streamlit apps

If you know the answer to a Streamlit user's pain point and want to add it to the KB:

1. Decide which of the above sections your article belongs to

2. Navigate to the relevant section's folder in kb/ and

3. Create a .md file in the above specified format containing your article

   • Make sure the title in the front matter and the file header in Markdown are identical. E.g.

     ---
     title: How do I add a Component to the sidebar?
     slug: /knowledge-base/components/add-component-sidebar
     ---
     
     # How do I add a Component to the sidebar?

4. Add a line to the existing index.md file in the same folder as your article. It should contain the title and URL slug specified in your article's front matter. This step ensures that users are able to discover your article in the index page of the relevant KB section. E.g.

   - [How do I add a Component to the sidebar?](/knowledge-base/components/add-component-sidebar)

Publishing

To publish your changes to the docs site:

1. Create a new branch containing your changes.
2. Create a Pull Request and mark Snehan as reviewers.
3. Once the checks have completed, checkout the Preview build.
4. Snehan will review your changes and merge your changes into the main branch.
5. Once merged, your changes will be live at https://docs.streamlit.io/.

docs's Issues

Docs should indicate that "magic" doesn't work in imported files

The magic docs should indicate that magic doesn't work for imported files.

Note

Eventually, we'd like to fix the underlying bug itself.

Add info on warning: Calling st.experimental_rerun() within a callback is a no-op

Link to doc page in question (if any):
https://docs.streamlit.io/library/api-reference/control-flow/st.experimental_rerun
Name of the Streamlit feature whose docs need improvement:
st.experimental_rerun
What you think the docs should say:
I have encountered a puzzling warning using st.button callback functions. The warning states:
Calling st.experimental_rerun() within a callback is a no-op.

I can't find any information about this warning except this pull request which appears to implement the warning Make calling st.experimental_rerun() within a callback a no-op which closes this issue: Rerunning the session does not work inside callbacks.

The simple test app I made using the following code triggers this warning (when buttons are pressed in succession) even though st.experimental_rerun is not explicitly run anywhere:

import streamlit as st

def left_callback():
    st.write('Left button was clicked')

def right_callback():
    st.write('Right button was clicked')

left_col, right_col, _ = st.columns([1, 1, 3])

with left_col:
    st.button('LEFT', on_click=left_callback)

with right_col:
    st.button('RIGHT', on_click=right_callback)

It appears that it is an issue with session state and callbacks not properly working together or the app being re-run inside one of the callbacks under the hood.

My suggestion is to add information about possible warnings that st.experimental_rerun() may trigger, including this one I have mentioned. Or add a functionality to suppress the warning. I don't think this is a bug, so I submit this as a documentation improvement in the hopes of getting some answers about why this warning is triggered.

Files not tracked if folder doesn't have __init__.py

Summary

I recently came across this issue and couldn't find anything in the documentation that called it out. I figured that either this is truly a bug, or the documentation should be updated to include a comment on this so that other users aren't caught off guard like I was.

Steps to reproduce

1. Create the following file structure. Fill each file as shown

app/
├── pages/
│    ├──page1.py
└── main.py

main.py:

import streamlit as st

from pages import page1

st.write('Main')
page1.display()

page1.py:

import streamlit as st

def display():
    st.write('Page 1')

2. Run streamlit run main.py
3. Change the text that's displaying in main.py. The streamlit app will offer to rerun in the browser as normal.
4. Change the text that's displaying in page1.py. The streamlit app will not offer to rerun. Any code changes to this file will not appear unless you restart the streamlit app from the command line.

Expected behavior:

Changing code in any files in subfolders would also be detected by Streamlit.

Actual behavior:

The changes in the subfolder files aren't detected by Streamlit.

Workaround:

Simply adding an empty __init__.py to pages/, killing the app, then restarting it will fix the issue. The working folder structure then looks like this:

app/
├── pages/
│   ├── __init__.py
│   └── page1.py
└── main.py

Is this a regression?

No idea, but probably not.

Debug info

• Streamlit version: 0.62.1
• Python version: 3.7.4

Improve docs about how widget IDs work

All Streamlit widgets have a key internally (and we actually call it id in the code). These keys are important since widget state is tracked as a key→value map. So when two widgets have the same key, things go crazy. (That's why we recently started showing a warning when that happens.)

The key is computed from a hash of the widget type and all the widget arguments. And we provide an extra kwarg called key that can be used to disambiguate. For example:

box1 = st.selectbox("", [1, 2, 3], key="box1")
box2 = st.selectbox("", [4,5,6], key="box2")

But none of this is in the docs! We should explain this somewhere.

Allow quick search via adress bar (link to search results)

Firefox has this handy option "Add a Keyword for this search":

I can add st as a keyword, but when I type st dataframe in Firefox's address bar, nothing really happens. I'm only dropped to the main page of the Streamlit docs. I assume this is because the search dialogue is a popup...

The URL turns to this: https://docs.streamlit.io/library/api-reference?=dataframe

An example, where searching via address bar keyword works, is https://devdocs.io/. I have the keyword dd for that and I can directly search in the search box of their web app.

Header jumps around when scrolling

See video:

Screen.Recording.2022-02-14.at.11.04.08.AM.mov

Styling for deprecated sections

Name of the Streamlit feature whose docs need improvement:
Going forward we would like to use the deprecated tag which adds a deprecated class. I would love to have this look the same as an info block. I'm not sure if it's possible to create a component for deprecated items or if we just have control over the CSS. If we have to we can use a pure CSS and force a header with a ::before class.

Desired:

"Join" image is blurry

Maybe we could use a higher resolution for that join.png image?

Add tutorial: Google Cloud Storage

I've started developing some apps with Streamlit and noticed there is no Knowledge Base tutorial for Google Cloud Storage (however there is one for Amazon S3).

I'm interested in contributing a new GCS tutorial to the docs and creating a PR for this change.

Should be very similar to the Streamlit tutorials for other Google data sources (BigQuery and Google Sheets) where we enable the API, create service account + key, add the secrets to the cloud, etc.

Mention integer length limitations in `number_input`

Link to doc page in question (if any): https://docs.streamlit.io/en/stable/api.html#streamlit.number_input

Name of the Streamlit feature whose docs need improvement: st.number_input

What you think the docs should say:

Hi folks! Found out when I was copy-pasting the integers generated by torch.seed() into st.number_input, that the last few digits went to zero after enter is pressed. There appears to be a limit for how long an integer input can be, which is something we don't deal with in Python, given its capability to natively handle big integers.

This appears to be floating point behaviour where the number ran out of significands. Digging around in the code base, seems that the Python side of the widget source code uses integers natively. Thus, I'm guessing that the limit to integer length is inherent to how Javascript stores the number internally before passing it to the Streamlit application. But I digress.

Anyway, I thought it would be worth mentioning number_input's limitation in handling big integers. As a workaround, users can use st.text_input and post-process the input values instead. This docs improvement should be relevant to folks building machine learning apps, where large ints can be involved in setting RNG seeds.

I'll put in a PR if the maintainers are OK w/ the proposed improvement.

benchmark with large dataset

Problem

Check if large dataset is supported in streamlit (how big it can go).
Its kind of useful if we try to put in production setup
and prevent crash if users use with bigger dataset.

Solution

Take some dataset like the taxi NYC and run it as Regression Tests or Unit Tests.

Additional context

Type of `OptionSequence` and return value of interactive widget

Link to doc page in question (if any):
https://docs.streamlit.io/en/stable/api.html#streamlit.radio

Name of the Streamlit feature whose docs need improvement:
Any interactive widget that receives an OptionSequence

What you think the docs should say:
All such widgets are typed so that they return a string. This is however not true since the type of the return value is dependent on the type of the options sequence. A generic approach is neeed here.

OptionSequence should be converted to

OptionGenericType = TypeVar('OptionGenericType')
OptionSequence = Sequence[OptionGenericType]

IMO the union is not needed since np.ndarray, pd.DataFrame and so on fullfill the sequence protocol

and the signature of e.g. selectbox will be:

 def selectbox(
        self,
        label: str,
        options: OptionSequence,
        index: int = 0,
        format_func=Callable[[OptionGenericType], str],
        key: Optional[Key] = None,
        help: Optional[str] = None,
        on_change: Optional[WidgetCallback] = None,
        args: Optional[WidgetArgs] = None,
        kwargs: Optional[WidgetKwargs] = None,
    ) -> OptionGenericType

I write this as my most common use case is to provide a list of TypedDicts to selectbox and then use format_func for formatting.

DuplicateWidgetID when running code in "Authentication without SSO"

Summary

When running code demo in Step 3: Ask for username & password in your Streamlit app, got error:
streamlit.errors.DuplicateWidgetID: There are multiple identical st.text_inputwidgets withkey='username'.

Steps to reproduce

Code snippet:
See summary.

Screenshot(s):
NA

Expected behavior:
No errors in terminal

Actual behavior:
See summary.

Add docs showing how to connect to Oracle Databases

Hiii Streamlit Team,
As per the documentation given here , currently Streamlit supports connection to Big Query , My Sql and various other databases . But I noticed that there is no functionality and module available to connect to Oracle Database .
Oracle Databases are used by lot of companies and adding module to connect to Oracle Database will make streamlit more complete and diverse library !
So can you please look into it and make the latest version available.
Thanks and Regards
Athar

Index page streamlit home page link not working

When Streamlit is clicked nothing happens, I checked index.md in /content folder, there's a link associated with Streamlit which should redirect to Streamlit homepage, but it isn't the case on the new documentation index page.

Darkmode doesn't work on drop down's text.

Hi, as the title suggests the drop down text isn't visible due to it having light background instead of a dark one.

An example in st.dataframe docs is missing

Link to doc page in question (if any):

https://docs.streamlit.io/library/api-reference/data/st.dataframe#stdataframe

Name of the Streamlit feature whose docs need improvement:

Code output/result

What you think the docs should say:

There are 3 code cells but only 2 outputs. The middle one, st.dataframe(df, 200, 100) has no output for example of streamlit dataframe component resized.

Add LICENSE file

@tvst I assume we'd use Apache 2.0 here as well?

Being more clear on terminal output when using streamlit with Docker

Problem

It took me a little while to realize that the reason why the Network URL for my streamlit Docker container wasn't working was that it isn't actually the URL I needed to access. I needed to go to localhost:8501 instead of the URL in Network URL. I had to just guess and try things to find this out.

Solution

Since this is different than when you simply run streamlit run app.py (this does give us the Local URL), I think it would be beneficial to either include this somewhere in the documentation (no Docker search results found in the streamlit docs) or print out localhost: in the terminal when we spin up a Docker container. From what I understand, streamlit already recognizes when it is being run in Docker (maybe not exactly) because it isn't automatically opening up a window for this exact reason (it knows Network URL is not what the user wants when running locally).

st.graphviz_chart examples not rendering

Summary

Was working on providing a small example of using graphviz to render Decision Tree in streamlit/streamlit#1330 but code did not work. Then tried the 2 examples from API reference and none worked on my machine. Then tried this one. All got the same errors about viz not being defined 🤔 is it only me ?

Steps to reproduce

graph = graphviz.Digraph()
graph.edge('run', 'intr')
graph.edge('intr', 'runbl')
graph.edge('runbl', 'run')
graph.edge('run', 'kernel')
graph.edge('kernel', 'zombie')
graph.edge('kernel', 'sleep')
graph.edge('kernel', 'runmem')
graph.edge('sleep', 'swap')
graph.edge('swap', 'runswap')
graph.edge('runswap', 'new')
graph.edge('runswap', 'runmem')
graph.edge('new', 'runmem')
graph.edge('sleep', 'runmem')
st.graphviz_chart(graph)

st.graphviz_chart('''
    digraph {
        run -> intr
        intr -> runbl
        runbl -> run
        run -> kernel
        kernel -> zombie
        kernel -> sleep
        kernel -> runmem
        sleep -> swap
        swap -> runswap
        runswap -> new
        runswap -> runmem
        new -> runmem
        sleep -> runmem
    }
''')

Expected behavior:

Displays graph

Actual behavior:

Frontend logs for me

Loading script from “http://localhost:8501/vendor/viz/viz-1.8.0.min.js” with importScripts() was blocked because of a disallowed MIME type (“text/plain”).
NetworkError: WorkerGlobalScope.importScripts: Failed to load worker script at http://localhost:8501/vendor/viz/viz-1.8.0.min.js
uncaught exception: Viz is not defined

Is this a regression?

Probably

Debug info

• Streamlit 0.57.4.dev20200408 and 0.57.3
• Python 3.7
• Conda, Windows 7 64 bit, Firefox

st.audio Static Embedded App does not work on Safari

Summary

Likely due to the old link https://static.streamlit.io/0.25.0-2JkNY/index.html?id=Dv3M9sA7Cg8gwusgnVNTHb being pinned to a version that did not have the Range Requests fix. We should see if re-making the Static Embedded App would fix this.

See slack discussion: https://streamlit.slack.com/archives/C0132LY8TA7/p1604518452081200

(On a broader level, our testing situation on Safari leaves something to be desired)

How about a documentation of Chinese version?

Hi, there! 🌞
I have been noticed this project since last October (the Version 0.47.0), after that I wrote several articles to introduce it on my wechat blog in Chinse. Some of my collegues shared their interest about it, so I also translated the API reference for them.
Nowadays, I wonder if I can contribute those Chinese documents back to this project. The latest Chinese version I have correspond to the Version 0.49.0.
With no doubt, I am happy to update those to the lateset Version, too.
Please let me know if you guys think it is useful and have willingness to attach it to the official documentation.
Best Regards
🎈🎈🎈

Create a Separate Section for Experimental + Beta features

Currently our documentation has beta features mixed in with our API. It'd be great to get a separate page for these beta/experimental features as these are subject to change/removal. Also would be nice to reiterate their state

Documentation: Potential Bad Backtick

Summary

Per one of our users on the forum "Docs seem broken just below here under ## Use Magic. I think due to a bad backtick"

Search modal cannot be closed by clicking the X (close) icon

After the search bar is clicked, it cannot be closed by clicking on the X icon. Only pressing the ESC key closes the search modal.

algolia-close.mp4

Master branch obsolete

Link to doc page in question (if any):
https://docs.streamlit.io/streamlit-cloud/get-started/deploy-an-app

Name of the Streamlit feature whose docs need improvement:
In "Your app URL" section the documentation seem to be outdated

What you think the docs should say:
The name of the branch should be main not master. See https://github.com/github/renaming Maybe this is the reason why the link https://share.streamlit.io/streamlit/demo-self-driving is not working

App Dependencies text not visible in Dark Mode

I was scrolling through the documentation and noticed that the portion inside Streamlit Cloud -> Get started -> Deploy an app -> App Dependencies is not visible.

This is how it looks.

Add documentation about how to use Streamlit with multiple threads.

TLDR: you either need to use the ReportThread class for your thread, or call add_report_ctx on your thread after creation

Add tutorial: Azure Blob Storage

Currently there is not a Knowledge Base tutorial for Azure Blob Storage.

I'm interested in contributing a new tutorial for Azure Blob Storage to the docs and creating a PR for this change.

Should be very similar to the existing S3 tutorial (creating a bucket + file, provisioning access keys, adding to secrets, etc.).

Secrets screenshot is outdated

This image public/images/databases/edit-secrets.png is outdated:

Also this page has outdated screenshots

This now looks different. And might also change soon (Environment in favor of Secrets), so need to keep that in mind.**

Documentation text color issue

Here is the link

This bit in the documentation when using the black theme is not readable.

plot,ly example keeps failing

Help Need: pip version issue

You are using pip version 21.1.1; however, version 22.0.3 is available.

You should consider upgrading via the '/home/appuser/venv/bin/python -m pip install --upgrade pip' command.

Redrawable types should be documented

Related to this: https://discuss.streamlit.io/t/force-redraw-of-an-earlier-element/635

Please add documentation of which types in DeltaGenerator are redrawable.

import time missing in tutorial

in the tutorial step "animate elements" the import statements are missing. using the statements from the previous examples does not work as import time is missing. It is added though in the next example: Return the value of a Streamlit call. I suggest you add the required import statements to all examples that should run on its own. I agree this might seem picky as the error is found quickly but the tutorial is just so much more impressive if everything just runs immediately.

Provide warning that dates are silently adjusted for the user's timezone

Link to doc page in question (if any):
https://docs.streamlit.io/en/stable/api.html#streamlit.line_chart

Name of the Streamlit feature whose docs need improvement:
st.line_chart

What you think the docs should say:

.. warning::
    Date formatted data will be adjusted for the user's timezone before being plotted on the ``st.line_chart``.

Details of issue:
The following image:

is produced by the following code:

st.write(icom_datasets)
st.line_chart(icom_datasets[["gantry", "collimator", "turn_table"]])

The plot and the dataframe print is produced by the same dataframe. The plot however silently removes (?) a presumed GMT+11 shift.

Confusion about python package management in "get started" docs

Mixing and mentioning different python packet managers is maybe confusing for beginners, especially if they move on from local development to streamlit cloud.

This is related to this forum thread:

https://discuss.streamlit.io/t/modulenotfounderror-despite-simple-requirements-txt-present/23795/10

The documentation first recommends to use pipenv and Pipfile for dependencies
But the next page says: “1. Put your app in a public GitHub repo (and make sure it has a requirements.txt!)”

Thanks but for a normal user who reads the documentation in order the first page is “Installation” where you’re told to use Pipfile and the next page is “Create an app” where you’re told to “make sure it has a requirements.txt!”.
It would be great to add a link to that page (“App dependencies”) in the “Installation” page of the documentation. And to mention clearly there that “You should only use one requirements file for your app. If you include more than one (e.g. requirements.txt and Pipfile). Streamlit will first look in the directory of your Streamlit app; however, if no requirements file is found, Streamlit will then look at the root of the repo.”

Docs UI glitch between 1025px and 1249px screen width

Problem

Between 1025px and 1249px screen width, the side bar overlays docs content, even if collapsed. Tested in Firefox 94.0 on my 1280x1024px screen (due to Ubuntu dash bar, actual browser window width is 1204px).

The screenshot demonstrates the behaviour. It is not possible to click links under the red area.

Solution

Fix media queries

Workaround

Zoom out or make window width smaller than 1025px.

Incorrect behavior description for st.cache

Link to doc page in question (if any): https://docs.streamlit.io/en/stable/api.html#streamlit.cache

Name of the Streamlit feature whose docs need improvement: cache

The docs for allow_output_mutation say:

Streamlit normally shows a warning when return values are not mutated, as that can have unintended consequences. This is done by hashing the return value internally.

If you know what you’re doing and would like to override this warning, set this to True.

However, based on the name, and behavior with the default value of False, it should say Streamlit normally shows a warning when return values are mutated, without the "not".

Create a deprecation page for docs

Suggestion:

As part of our deprecation process, we will be adding warnings prior to deprecation when to-be deprecated functionalities are used. This can be disabled by the developer

Option 1: In your streamlit app

st.set_config('deprecation.v00_051_showPyDeckWarning', False)

Option 2: In .streamlit/config.toml

[deprecation]
v00_051_showPyDeckWarning = False

Additional items

References for more info to include:
https://www.notion.so/streamlit/Proposed-Handling-Deprecation-Breaking-Changes-927c6172822c4277a6b07b4703723204
https://www.notion.so/streamlit/Let-s-talk-about-deprecation-warnings-67885d263aa14bb1af59b497e6880a07

Search is broken. Typing in the search bar does nothing.

@tvst I think this is a P0 or P1. One of the recent commits must have broken search. Clicking on the search bar brings up the search modal. However, typing into it does not cause search results to be displayed anymore. Additionally, clicking the X does not close the search modal.

search-broken.mp4

Autofunctions for `components.v1.html`, `components.v1.iframe` are broken

The following autofunctions are broken:

• <Autofunction function="streamlit.components.v1.html" />
• <Autofunction function="streamlit.components.v1.iframe" />

When used in the API Reference, the following error message is displayed:

Inline code within bulleted lists is not highlighted in orange

Elsewhere in the docs, when code is enclosed within ` `, the code is highlighted in orange. E.g.

When included in a bulleted list, the font changes, but the code is not highlighted in orange. E.g.

Japanese version of ducumentation?

Name of the Streamlit feature whose docs need improvement:
I think it's nice to have a Streamlit documentation in Japanese. There are so many Japanese articles about Streamlit, and I also did write a blog before.

If you want a Japanese translation and its maintenance, I would love to help it out!

remarks

Last year there was an issue about making a Chinese version of it ( #99 )

"App model" fragment in the "Main concepts" docs page seems broken

Navigating to https://docs.streamlit.io/library/get-started/main-concepts#app-model does not scroll the page down to the corresponding section. I tried navigating to a few other parts of the page via fragment, and they don't seem to be running into the same issue.

What seems to be a related bug is present when clicking on the page navigation links on the right hand side of the page -- clicking on the "App model" link brings you to the caching header.

3000 port is development port

Link to doc page in question (if any):
https://docs.streamlit.io/en/stable/streamlit_configuration.html

Name of the Streamlit feature whose docs need improvement:
Need to add a new line

What you think the docs should say:
Reserve port 3000 port in streamlit or reverse proxy. If you use it, it can do weird behavior
Reserve port 3000 because it is used for the development

Supabase as a Data Source for Streamlit

Hey Streamlit,

I am one of the maintainers of the python client libraries for Supabase . Supabase is, loosely speaking, an open source firebase. Streamlit is a great product and I was hoping that we could file a PR with a guide on how to use Supabase as a data source for Streamlit.

Wanted to seek your approval before doing this though.

Let us know!
Joel

Add in images or S4A apps or Static Embedded Apps in tutorials

In the tutorial-based sections of our docs, we should provide a visual component showing what the code snippets they run will look like. This serves two benefits:

1. Users who are running the tutorial get a way to check that they're doing the right thing
2. Users who aren't running the tutorial (or are deciding whether to) can learn what Streamlit would do

The simplest implementation of this would be screenshots, which would provide ~80% of the benefits for ~20% of the effort. If we wanted to get fancier, we could go on to make them live S4A apps or static embedded apps so users can directly interact with Streamlit.

Link to doc page in question (if any):

E.g.
https://docs.streamlit.io/en/stable/index.html
https://docs.streamlit.io/en/stable/getting_started.html
https://docs.streamlit.io/en/stable/tutorial/create_a_data_explorer_app.html

Improve docs about st.slider() support for ranges

Link to doc page in question (if any):
https://streamlit.io/docs/api.html#streamlit.slider

Name of the Streamlit feature whose docs need improvement:
st.slider

What you think the docs should say:
It's not super clear that you can pass a tuple to create a range slider.

And perhaps we should also mention it in get started

Static Embedded Apps should be generated effortlessly

Right now, there's still a ton of manual work that goes into creating and updating a static embedded app. And the result is that we don't use them as much as we could, plus the ones we use may be many versions out of date.

(For example, I'm thinking of making a fix to st.bar_chart streamlit/streamlit#2091 , but I'm almost sure I won't update the static embedded app because it's too much of hassle.)

Some issues:

1. Have to manually sync up the docstring with the example app (esp tedious with the >>> and ... prefixes in docstrings)
2. Have to build the distributed version of the frontend
3. Have to run the example app locally
4. Have to wait for the app to update

Ideally:

• Have example apps for basically all docstring examples
• As part of the release build process, all these apps get regenerated and uploaded with the latest Streamlit version
• Bonus: if all the apps share the same frontend framework, the associated frontend code only needs to be loaded once (as opposed to separately for each version 0.23/0.45/0.51/whatnot)
• SUPER STRETCH GOAL: Get widgets to work somehow (build these as an iframe into S4A?)