Meta tags:
description= The interactive graphing library for Python :sparkles: - plotly.py/doc at main · plotly/plotly.py;
Headings (most frequently used words):
build, doc, directory, api, fails, navigation, and, tutorial, building, the, documentation, of, file, breadcrumbs, actions, more, options, files, tutorials, ci, footer, new, page, deployment, prod, single, plotly, py, menu, repository, filesexpand, tree, latest, commit, history, folders, readme, md, introduction, structure, required, packages, local, environment, setup, python, reference, apidoc, cd, pipeline, troubleshooting, parent, branching, strategy, format, creating, guidelines, process, docs, how, works, adding, objects, other, what, triggers, steps, only, summary, full, path, to, make, immediately, on, graph_objs, references, frontmatter, validation, keeping, main, in, sync, all, output,
Text of the page (most frequently used words):
the (138), #plotly (52), and (51), doc (49), build (40), python (33), are (27), for (27), html (23), files (23), you (20), prod (19), main (19), docs (18), github (18), with (17), page (17), api (16), documentation (16), that (14), install (14), your (13), name (13), built (12), tutorial (12), all (12), directory (12), branch (12), feature (12), jupyter (11), version (11), make (11), rst (11), into (11), code (11), not (10), pages (10), source (10), should (10), order (9), from (9), site (9), file (9), can (8), frontmatter (8), graph_objs (8), jupytext (8), sphinx (8), notebook (8), when (8), pip (8), deployed (8), markdown (8), apidoc (8), examples (8), runs (7), description (7), check (7), more (7), tutorials (7), only (7), requirements (7), txt (7), new (7), release (7), released (7), navigation (6), display_as (6), environment (6), example (6), library (6), https (6), com (6), actions (6), features (6), pull (6), bar (6), will (6), merged (6), this (5), time (5), security (5), category (5), language (5), permalink (5), fails (5), installed (5), output (5), failures (5), single (5), graphing (5), path (5), repository (5), changes (5), editable (5), request (5), contains (5), filename (5), 2019 (5), charts (5), each (5), need (5), required (4), checkout (4), temporarily (4), references (4), nbconvert (4), full (4), commit (4), reference (4), local (4), available (4), what (4), graph_objects (4), written (4), venv (4), building (4), next (4), title (4), cell (4), copy (4), have (4), used (4), search (4), open (4), update (4), thumbnail (4), tab (4), tpl (4), options (4), support (4), copilot (4), footer (3), yaml (3), existing (3), same (3), layout (3), validation (3), timeout (3), sure (3), jekyll (3), live (3), workflow (3), final (3), branches (3), artifact (3), within (3), development (3), inside (3), dependencies (3), setup (3), also (3), etc (3), found (3), objects (3), corresponding (3), write (3), express (3), use (3), makefile (3), bin (3), activate (3), process (3), uses (3), extension (3), specific (3), date (3), using (3), what_about_dash (3), short (3), run (3), cells (3), blocks (3), basic (3), metadata (3), updating (3), see (3), merge (3), fixes (3), described (3), been (3), which (3), edit (3), readme (3), history (3), quality (3), another (3), window (3), refresh (3), session (3), reload (3), sign (3), developers (3), changelog (3), customer (3), enterprise (3), grade (3), community (2), status (2), fields (2), value (2), does (2), enforce (2), front (2), matter (2), git (2), modifies (2), them (2), virtual (2), activated (2), needs (2), issue (2), before (2), imports (2), error (2), deploys (2), rebuild (2), deployment (2), triggers (2), downstream (2), generates (2), intermediate (2), contents (2), uploaded (2), named (2), then (2), ordering (2), kj8 (2), pypi (2), system (2), steps (2), validated (2), push (2), but (2), any (2), event (2), automatically (2), workflows (2), configuration (2), how (2), autodoc (2), other (2), object (2), added (2), class (2), basefigure (2), figure_factory (2), subplots (2), module (2), back (2), color (2), generate (2), colors (2), internal (2), uninstall (2), its (2), redirect (2), pattern (2), displayed (2), just (2), why (2), prefix (2), without (2), one (2), parallel (2), previews (2), converts (2), about (2), execute (2), typically (2), they (2), possible (2), engines (2), most (2), set (2), jupyterlab (2), work (2), fenced (2), block (2), change (2), structure (2), right (2), creating (2), regular (2), text (2), example_index (2), page_type (2), maps (2), scientific (2), statistical (2), url (2), match (2), sidebar (2), important (2), seo (2), pin (2), newly (2), fail (2), already (2), case (2), writing (2), yet (2), off (2), below (2), website (2), soon (2), two (2), edits (2), where (2), contributing (2), notes (2), link (2), top (2), dependency (2), packages (2), next_redirect (2), unconverted (2), last (2), message (2), breadcrumbs (2), latest (2), insights (2), 649 (2), signed (2), universe (2), training (2), integrations (2), stories (2), center (2), learn (2), business (2), products (2), secret (2), perform, action, share, personal, information, manage, cookies, contact, privacy, terms, 2026, inc, against, ensure, includes, conflict, under, previous, was, interrupted, those, may, dirty, state, reset, confirm, running, immediately, default, 600, seconds, minutes, legitimately, discuss, increasing, remote, data, urls, correct, missing, import, dataset, common, causes, troubleshooting, triggered, generation, summary, after, deploying, pushing, empty, built_ipynb, target, pushed, three, inspection, upload, twice, retry, transient, downloads, scripts, verifies, categories, validates, non, replaces, utility, rename, happens, defined, yml, pipeline, theme, extensions, conf, template, templates, describe, different, look, like, _templates, _static, css, exposed, appear, subplot, helpers, display, read, traces, high, level, lists, documented, submodules, adding, renames, generated, related, cleans, copied, reverts, produce, auto, stubs, excluding, offline, matplotlylib, tests, validators, copies, their, docstrings, picked, rewrites, cross, resolve, performs, several, works, _build, require, because, renaming, reverting, afterward, rest, markup, stderr, logs, failed, redir, ipynb, whose, collection, processes, matching, silently, ignores, anything, else, arbitrary, placeholder, never, satisfies, parser, yyyy, ext, _posts, follows, useful, during, flag, continues, past, jobs, backward, compatibility, outputs, executes, minute, per, appends, dash, through, every, too, long, 10s, since, part, continuous, integration, taking, longer, discussed, decide, whether, accepted, variable, names, consistent, pandas, dataframe, figure, fig, package, called, paste, reproduce, clear, titles, indexed, checklist, try, standalone, almost, self, explaining, focus, guidelines, passes, optional, instead, entire, directly, verify, lab, test, becomes, separate, converted, minimum, matches, starting, point, get, tag, separated, blank, line, starts, between, image, numeric, sort, grouping, file_settings, 3d_charts, slug, must, shown, browser, field, enter, correctly, jpg, position, base, ipython3, pygments_lexer, nbconvert_exporter, mimetype, file_extension, ipython, codemirror_mode, language_info, python3, ipykernel, display_name, kernelspec, jupytext_version, format_version, format_name, text_representation, notebook_metadata_filter, here, annotated, categorization, format, synchronizing, pinned, rely, stale, prep, repo, bump, versions, algolia, indexes, section, procedure, publish, outstanding, done, recently, synchronization, bidirectional, prevent, diverging, basis, via, keeping, sync, ready, such, upcoming, updated, made, publicly, branching, strategy, clone, developing, restart, kernel, changed, small, correcting, typos, simply, click, clicking, take, opened, installing, remove, documenting, has, reflected, step, geopandas, gdal, locally, dedicated, listed, generating, hosted, composed, parts, introduction, outline, view, parent, folders, expand, tree, items, requests, issues, dismiss, alert, switched, accounts, out, appearance, settings, pricing, talks, workshops, partners, company, forum, events, webinars, blog, resource, connect, resources, premium, advanced, add, ons, trust, evaluate, industries, government, manufacturing, financial, services, healthcare, industry, nonprofits, startups, team, enterprises, stage, businesses, improvements, across, place, developer, articles, sponsors, trending, repos, explore, customize, certifications, scanning, leak, prevention, protection, vulnerability, detection, remediation, secure, cloud, environments, codespaces, analysis, enforcement, automation, ship, coding, agent, tasks, projects, automated, hosting, review, collaboration, platform, menu, skip, content,
Text of the page (random words):
gation menu sign in products platform github repository hosting code review and collaboration copilot ai coding agent for tasks projects and automated work build ship actions ci cd and automation code quality quality analysis fixes and enforcement codespaces cloud development environments secure code security vulnerability detection and remediation secret protection secret scanning and leak prevention all features developers learn documentation training certifications build build with copilot customize copilot integrations explore trending repos github sponsors developer articles changelog changelog your source for the latest features improvements and fixes across github products all in one place businesses by stage enterprises team startups nonprofits by industry healthcare financial services manufacturing government see all industries evaluate github why github customer stories business insights trust center add ons github advanced security enterprise grade code security copilot for business enterprise grade ai features premium support enterprise grade 24 7 support resources learn connect documentation resource center blog events webinars community forum customer stories integrations support customer support training github status company about partners changelog github universe github universe the event for developers by developers talks workshops and what s next for github pricing search sign in sign up appearance settings you signed in with another tab or window reload to refresh your session you signed out in another tab or window reload to refresh your session you switched accounts on another tab or window reload to refresh your session dismiss alert message plotly plotly py repository navigation code issues 649 649 pull requests 87 87 actions security and quality insights more items files expand file tree main breadcrumbs plotly py doc copy path directory actions more options more options directory actions more options more options latest commit history history history main breadcrumbs plotly py doc copy path top folders and files name name last commit message last commit date parent directory apidoc apidoc python python unconverted python unconverted python makefile makefile readme md readme md nb tpl nb tpl next_redirect tpl next_redirect tpl requirements txt requirements txt what_about_dash md what_about_dash md view all files readme md outline documentation of plotly py introduction structure and required packages the doc directory contains the source files of the documentation of plotly py it is composed of two parts inside the python directory tutorials corresponding to https plotly com python inside the apidoc directory configuration files for generating the api reference documentation hosted on https plotly com python api reference python packages required to build the docs are listed in requirements txt in the doc directory local environment setup before building the documentation locally you need to set up a dedicated environment with the doc specific dependencies you will need the gdal system library installed it s a build dependency of geopandas a required dependency the uv pip install step below will fail without it cd doc uv venv python 3 10 source venv bin activate uv pip install r requirements txt if you are documenting a feature that has not yet been released you also need an editable install of plotly so your local changes are reflected uv pip uninstall plotly remove the pypi version installed by requirements txt uv pip install e install from your local checkout tutorials python directory each tutorial is a markdown md file which can be opened in jupyter notebook or in jupyterlab by installing jupytext for small edits e g correcting typos to an existing tutorial you can simply click on the edit this page on github link at the top right of the page e g clicking on this link on https plotly com python bar charts will take you to https github com plotly plotly py edit doc prod doc python bar charts md where you can edit the page on github for more important edits where you need to run the notebook to check the output clone the repository and setup an environment as described in the main contributing notes if you re writing documentation at the same time as you are developing a feature make sure to install with editable install pip install e as described in main contributing notes so that you only need to restart the jupyter kernel when you have changed the source code of the feature branching strategy the doc prod branch contains the live docs which are available on the website as soon as a change is merged into doc prod the updated docs are deployed and made publicly available the main branch contains docs which have been written but are not ready to be released such as for an upcoming feature in the next plotly py release when updating the docs two workflows are possible in the case of updating the docs for an already released feature your changes can be deployed to the documentation website as soon as they have been merged so you should branch off of the doc prod branch and open your pull request into the doc prod branch in the case of writing docs for a new not yet released feature you should branch off main and open your pull request into main so that the documentation of the feature is only deployed when it is available in a released version of plotly py the main branch will be merged into doc prod at release time as described below keeping main and doc prod in sync changes to doc prod are not automatically merged back into main to prevent the branches from diverging doc prod should be merged into main on a regular basis via a pull request e g a branch named merge doc prod to main branch merged into main at release time the synchronization is bidirectional see also release md doc prod main merge any outstanding doc only fixes into main if not already done recently main doc prod merge main into doc prod so that documentation for newly released features is deployed to the live site publish the site update the graphing library docs repo to bump the plotly py and plotly js versions and rebuild the algolia search indexes see the update documentation site section of release md for the full procedure release prep when synchronizing main into doc prod for a new release update the plotly version pin in doc requirements txt to match the newly released version the doc prod build uses this pinned version not an editable install so examples that rely on new features will fail if the pin is stale tutorial file format tutorial files are markdown files with a yaml frontmatter block that contains jupyter notebook metadata used by jupytext and plotly specific metadata used by the documentation site for navigation seo and categorization here is an annotated example of the frontmatter jupyter jupytext notebook_metadata_filter all text_representation extension md format_name markdown format_version 1 3 jupytext_version 1 17 3 kernelspec display_name python 3 ipykernel language python name python3 language_info codemirror_mode name ipython version 3 file_extension py mimetype text x python name python nbconvert_exporter python pygments_lexer ipython3 version 3 9 0 plotly description short description for seo and page previews display_as basic category basic statistical scientific maps 3d etc language python layout base name page title displayed in the navigation sidebar order 3 position within the display_as category page_type example_index permalink python my page url path on the documentation site thumbnail thumbnail my page jpg the plotly metadata fields are the most important to enter correctly when creating updating a tutorial field description name page title shown in the sidebar and browser tab permalink url slug must match the filename e g bar charts md python bar charts description short description used by search engines display_as category grouping e g basic statistical scientific maps 3d_charts file_settings order numeric sort order within the category page_type typically example_index for tutorial pages thumbnail path to the thumbnail image code cells are written as fenced code blocks with the python language tag each code cell is separated by a blank line and starts with python markdown cells are written as regular markdown text between code blocks creating a new tutorial page copy an existing tutorial from doc python as a starting point to get the frontmatter structure right update the frontmatter at minimum change name permalink description display_as and order make sure permalink matches the filename e g my feature md python my feature write examples using fenced python code blocks each block becomes a separate jupyter cell when the file is converted test in jupyter open the file directly in jupyterlab with jupytext installed and run all cells to verify the examples work jupyter lab doc python my feature md build the single page optional you can build just your page instead of the entire doc set cd doc make build html 2019 07 03 my feature html check that ci passes push your branch and open a pull request the ci will build all pages and run validation on frontmatter and page ordering guidelines we try to write short standalone and almost self explaining examples most examples should focus on a single feature checklist each example should have a clear title titles are used for the navigation bar and indexed by search engines package imports should be called in the same cell as the example so that it is possible to copy paste a single cell to reproduce the example variable names should be consistent with other examples for example use fig for a figure object df for a pandas dataframe etc examples should not be too long to execute typically 10s since the doc is built as part of the continuous integration ci process examples taking longer to execute should be discussed in a new issue to decide whether they can be accepted build process building all tutorials from the doc directory with the virtual environment activated cd doc source venv bin activate make this runs through every md file in python and appends the what about dash footer from what_about_dash md converts each markdown file to a jupyter notebook using jupytext executes the notebook and converts it to html using nbconvert with a 10 minute timeout per notebook outputs html files to build html with a 2019 07 03 date prefix generates redirect pages for v3 backward compatibility and next version previews to build in parallel as ci does make kj8 the k flag continues past failures and j8 runs 8 jobs in parallel building a single tutorial to build only one page useful during development make build html 2019 07 03 bar charts html the filename follows the pattern 2019 07 03 markdown filename without extension html why the 2019 07 03 prefix the downstream graphing library docs site uses jekyll whose _posts collection only processes files matching the pattern yyyy mm dd title ext and silently ignores anything else the specific date is an arbitrary placeholder its value is never displayed it just satisfies jekyll s filename parser build output directory contents build ipynb intermediate jupyter notebook files build html final html tutorial pages build html redir redirect pages v3 and next version build failures stderr logs for pages that failed to build if a build fails check build failures page name for the error output api reference documentation apidoc directory we use sphinx and its autodoc extension in order to generate the documentation of the api sphinx uses the rest markup language building the api docs the api docs require an editable install of plotly because the build process temporarily modifies source files renaming graph_objects references to the internal graph_objs name for sphinx then reverting afterward cd doc source venv bin activate uv pip uninstall plotly uv pip install e cd apidoc make html the output is written to apidoc _build html how the api doc build works the apidoc makefile performs several steps temporarily rewrites class cross references in plotly graph_objs to use the internal graph_objs name so sphinx can resolve them copies color module files into plotly colors and plotly express colors so their docstrings are picked up runs sphinx apidoc to auto generate rst stubs from the python source excluding validators tests matplotlylib offline and api runs sphinx build to produce html from the rst files reverts the graph_objs source changes with git checkout cleans up the temporarily copied color files renames all graph_objs references back to graph_objects in the generated html and related files adding new api objects lists of objects to be documented are found in rst files corresponding to submodules file module plotly express rst plotly express high level api plotly graph_objects rst plotly graph_objects traces layout plotly io rst plotly io display read write plotly subplots rst plotly subplots subplot helpers plotly figure_factory rst plotly figure_factory basefigure rst basefigure class when a new object is added to the exposed api it needs to be added to the corresponding rst file to appear in the api doc other files css files are found in _static template files are found in _templates rst templates describe how the autodoc of the different objects should look like conf py contains the sphinx configuration theme extensions etc ci cd pipeline documentation is built and deployed automatically by the github actions workflow defined in github workflows build doc yml what triggers a build event what happens pull request any branch tutorials markdown files in doc python are built and validated the build artifact is uploaded but not deployed push to doc prod full build tutorials are built validated and deployed api docs are also built and deployed build steps environment setup python 3 10 uv and system dependencies rename utility are installed install doc dependencies uv pip install r requirements txt inside doc install editable plotly non doc prod branches only replaces the pypi plotly with the local checkout so that in development features are available build html tutorials runs make kj8 twice to retry transient failures then downloads and runs validation scripts from plotly graphing library docs front matter ci py validates the yaml frontmatter of all built pages check or enforce order py verifies page ordering within categories upload build artifact the built html is uploaded as a github actions artifact named doc html for inspection deployment doc prod only when changes are pushed to doc prod the workflow deploys to three branches of the plotly plotly py docs repository target branch contents built final html tutorial pages built_ipynb intermediate jupyter notebook files gh pages api reference html built by sphinx after deploying the workflow triggers a downstream build in plotly graphing library docs by pushing an empty commit that repository generates the final https plotly com python site summary of the full de...
|