This repository contains the sources for the Shiny for Python web site.
Install Quarto. Because Quarto is under rapid development, it's best to install by cloning the Quarto git repository and running a setup script; after that, just doing git pull
will make the latest version available, without needing to run an installer each time. Instructions here.
Clone this repository:
git clone https://github.com/rstudio/pyshiny-site.git
cd pyshiny-site
Set up git submodules:
make submodules
Build everything (see Notes below for information on individual steps, which can be run separately):
make all
Serve the website and watch for changes to the .qmd files:
make serve
Running make
by itself will print out the available make
targets:
$ make
all Build everything
submodules Update git submodules to commits referenced in this repository
submodules-pull Pull latest commits in git submodules
build_pkgs Build and install htmltools and shiny
shinylive Build JS components for shinylive
pypi Create a local pypi repository with htmltools and shiny
api_docs Build shiny API documentation
site Build website
serve Build website and serve
clean Remove Quarto website build files
distclean Remove all build files (packages, API docs, shinylive, Quarto website)
The make all
command runs the following steps. If you are iterating on the site, it will be more efficient to run these steps individually as needed.
Install Python packages needed for building the site:
make deps
Build qmd files for Shiny API docs. These will go in api/.
make quartodoc
Build the site:
make site
When running make
, all of the Python scripts and commands run in a virtualenv. If you want to run commands at the terminal in the same virtualenv, you will need to do the following:
Set up virtualenv (this only needs to be done once, and is done automatically by make all
):
make venv
After the virtualenv is created, activate it with:
source venv/bin/activate
This will make the virtualenv available when you run commands at the terminal.
Deactivate the virtualenv with:
deactivate
To pull the latest changes:
git pull
Update submodules. For example, if the upstream pyshiny-site points to a new commit in shinylive, this will update the local shinylive to that commit.
make submodules
Install dependencies and build the site:
make all
In some cases, you may need to run make clean
, to make sure everything is rebuilt properly.
This site is built using a number of Quarto extensions. The extensions are checked into the repository so they do not need to be installed separately. However, if you want to update the extensions to the latest version, you can do so by running:
make quarto-exts
Then commit the changes to the repository.
Normally, any commits on the main
branch will automatically be built and deployed on the gh-pages
branch using GitHub Actions. (Note: the reason that the site is built to the docs/
directory is because that's what GitHub Pages uses.)
If you want to manually deploy the site, follow the build instructions above on the main
branch (or another branch -- but typically not gh-pages
), then run:
git checkout -B gh-pages
git add docs
git push -f
By default, the submodules will have a specific commit checked out in detached HEAD mode; they will not have a branch checked out. If you want to do develop on the submodules, you may need to check out a branch like main
. Note that when you do have a branch checked out in a submodule, you need to be careful to make sure it doesn't get out of sync with the commit that the parent project wants the submodule to be on.