tb-file

The tb-file directive describes a simulated local file. A file can be shown in the document, hidden for later execution use, or attached to a tb-code execution request.

Synopsis

The general format of the tb-file directive is:

.. tb-file::
   :filename: required-filename
   :optional parameter: value

   + --- File content area ---
   |
   | one or more lines of file content
   |
   + -------------------------

The filename option is required. Inline content or a referenced source file is required.

The directive can also read content from a source file in the Sphinx project:

.. tb-file:: examples/input.txt
   :filename: input.txt

Options

filename

String. Required. The simulated local filename. This is the filename that code should expect when the file is attached to an execution environment.

Filenames may contain only letters, numbers, dots, underscores, hyphens, and forward slashes and must be relative paths. Empty path segments, ., .., absolute paths, spaces, and other punctuation are rejected.

alt

String. Optional. An equivalent description of an image or binary file. Used as HTML image alternate text and tagged PDF figure metadata. Describe instructional meaning, not the filename. This follows the Docutils image alt option.

caption

String. Optional. Caption displayed with the static file listing.

class

String or List. Optional. A CSS class to add to the directive. See Common options for details.

encoding

String. Optional. Encoding used when reading a referenced text file. Default is utf-8.

hidden

Boolean. Optional. If present, register the file but do not render it in output. Hidden text files must also use :readonly:; otherwise Sphinx emits a build warning because a hidden file has no editor.

name

String. Optional. Sphinx reference name for this file artifact. See Common options for details.

readonly

Boolean. Optional. If present, do not add editing controls for text files in HTML. Text files are editable by default. Binary files are never editable.

Sphinx configuration options

No directive-specific configuration options exist.

Accessibility behavior

Visible text files render their caption, or their filename when no caption is set, and their content as readable preformatted text before JavaScript runs. When editing is available, HTML adds a native button and textarea with programmatic labels.

Use :alt: to describe image content. HTML falls back to the filename when no description is provided; tagged PDF builds warn about missing image alt text. PNG, JPEG, and PDF assets render as figures in LaTeX output. Unsupported binary formats render a file reference and the supplied description.

Fallback behavior

Text builders render visible text files as labeled file listings. PDF-oriented builders render visible text files as LaTeX listings. The listing caption uses caption when set and otherwise uses filename. Compatible images render as figures with captions. Hidden files are not rendered, but remain available in the Sphinx environment registry for later execution integration.

Referenced binary files are registered and marked read-only. HTML can display image formats supported by browsers. Text output always supplies a file reference and description. PDF output embeds PNG, JPEG, and PDF assets and supplies a textual reference for other binary formats. Authors should use builder-specific only sections when a binary file format is suitable for one output format but not another, such as a PostScript file for LaTeX-oriented output.

Examples

Example 1: Inline text file

Source

.. tb-file::
   :filename: input.txt
   :caption: Example input file

   Hello file!

Rendered

Example input file

Hello file!

Example 2: Hidden text file

Source

.. tb-file::
   :filename: data/input.txt
   :hidden:
   :readonly:

   100

Rendered

The file is registered but not displayed.

Example 3: Reading a simulated file from C++

This example uses text from Lewis Carroll’s Jabberwocky. When Run is pressed, the current contents of poem.txt are sent with the execution request. Edit the visible tb-file listing to change the uploaded content.

Source

.. tb-file::
   :filename: poem.txt
   :caption: Lewis Carroll's *Jabberwocky*

   Beware the Jabberwock, my son!
     The jaws that bite, the claws that catch!

   (remainder ommitted)

.. tb-code:: c++
   :caption: Read a simulated local file
   :files: poem.txt

   #include <fstream>
   #include <iostream>

   int main () {
     std::ifstream is("poem.txt");
     char c;
     while (is.get(c)) {
       std::cout << c;
     }
     is.close();
     return 0;
   }

Full Text file

Lewis Carroll's *Jabberwocky*

Beware the Jabberwock, my son!
  The jaws that bite, the claws that catch!
Beware the Jubjub bird, and shun
  The frumious Bandersnatch!"

He took his vorpal sword in hand:
  Long time the manxome foe he sought --
So rested he by the Tumtum tree,
  And stood awhile in thought.

And, as in uffish thought he stood,
  The Jabberwock, with eyes of flame,
Came whiffling through the tulgey wood,
  And burbled as it came!

One, two! One, two! And through and through
  The vorpal blade went snicker-snack!
He left it dead, and with its head
  He went galumphing back.

And, has thou slain the Jabberwock?
  Come to my arms, my beamish boy!
O frabjous day! Callooh! Callay!'
  He chortled in his joy.

Rendered

Read a simulated local file

#include <fstream>
#include <iostream>

int main () {
  std::ifstream is("poem.txt");
  char c;
  while (is.get(c)) {
    std::cout << c;
  }
  is.close();
  return 0;
}