diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bafbc2f..deb99c5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -47,7 +47,20 @@ jobs: strategy: fail-fast: false matrix: - platform: ["macOS-latest", "windows-latest", "ubuntu-latest"] + include: + - name: macOS + platform: macOS-latest + + - name: windows + platform: windows-latest + + - name: ubuntu-24.04 + platform: ubuntu-24.04 + system-dependencies: | + sudo apt-get update + sudo apt install gir1.2-gtk-3.0 gir1.2-webkit2-4.1 \ + libcairo2-dev libcanberra-gtk3-module libgirepository-2.0-0 \ + libgirepository-2.0-dev steps: - name: Checkout @@ -55,17 +68,19 @@ jobs: with: fetch-depth: 0 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v6.2.0 - with: - python-version: 3.14 + - name: Install uv + uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 + + - name: Install system dependencies + if: matrix.system-dependencies + run: ${{ matrix.system-dependencies }} - - name: Install dependencies + - name: Build package run: | - uvx briefcase package + uvx briefcase package --adhoc-sign - name: Upload artefacts uses: actions/upload-artifact@v7.0.1 with: - name: installer-${{ matrix.platform }} + name: installer-${{ matrix.name }} path: dist diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index fb141c6..555290d 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -19,6 +19,10 @@ repos: - id: ruff-format - id: ruff-check args: [--fix] + - repo: https://github.com/rvben/rumdl-pre-commit + rev: v0.1.87 + hooks: + - id: rumdl # - repo: https://github.com/codespell-project/codespell # rev: v2.4.2 # hooks: diff --git a/.pyspelling.yml b/.pyspelling.yml new file mode 100644 index 0000000..f1c7097 --- /dev/null +++ b/.pyspelling.yml @@ -0,0 +1,69 @@ +matrix: +- name: markdown + aspell: + lang: en + d: en_US + mode: + - markdown + - url + - email + dictionary: + wordlists: + - docs/spelling_wordlist + output: _build/dictionary/python.dic + sources: + - 'docs/**/*.md' + - README.md + pipeline: + - pyspelling.filters.markdown: + markdown_extensions: + - markdown.extensions.toc + - markdown.extensions.admonition + - markdown.extensions.attr_list + - pymdownx.superfences + - pymdownx.blocks.admonition + - pymdownx.blocks.caption + - pymdownx.blocks.tab + - pymdownx.details + - pyspelling.filters.html: + comments: false + attributes: + - title + - alt + ignores: + - 'code' + - 'pre' + - 'nospell' + - pyspelling.filters.context: + context_visible_first: true + delimiters: + # Ignore the Jinja directives + - open: '{% ' + close: ' %}' + # Ignores the autorefs link targets + - open: '\]\[' + close: '\]' + # Ignore the single line Snippets syntax + - open: '-8<- ' + close: '$' + # Ignore the .md URLs - appears to be fixed by mode: url above, leaving in place for now + #- open: 'https?:' + # close: '\.md(:[-\w]+)?' + # Ignore urls in frontmatter - This is still necessary with mode: url + - open: 'url: ' + close: '$' + # Ignore toc in frontmatter + - open: '- toc' + close: '$' + # Ignore numbers with a suffix, e.g. dates + - open: '[0-9]+' + close: '[rshndt]*' + # Ignore version numbers + - open: '[0-9\.]+[a-z]*' + close: '[0-9]*' + # Ignore URLs in Markdown links - This shouldn't be necessary, but here we are. + - open: '\]\(' + close: '\)' + # Ignore attrlist class names + - open: '\{ \.' + close: '\}' diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..21e682d --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,20 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-24.04 + tools: + # Docs are always built on Python 3.13. See also the tox config. + python: "3.13" + jobs: + pre_install: + - python -m pip install --upgrade pip + - python -m pip install --group 'tox-uv' + build: + html: + - python -m tox -e docs-all -- --output=$READTHEDOCS_OUTPUT/html/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..8da6e47 --- /dev/null +++ b/README.md @@ -0,0 +1,92 @@ +# Podium + +[![image](https://beeware.org/project/projects/applications/podium/podium.png){width="72px"}](https://beeware.org/project/projects/applications/podium) + +[![Discord server](https://img.shields.io/discord/836455665257021440?label=Discord%20Chat&logo=discord&style=plastic)](https://beeware.org/bee/chat/) + +A markup-based slide presentation tool. + +## Why? + +## Quickstart + +Official releases of Podium can be downloaded from the [GitHub releases page](https://github.com/beeware/podium/releases). + +Download the binary for your platform of choice, and run it. This should open a file dialog, prompting you to open a `.podium` slide deck. An example Podium slide deck is also available in the releases folder. Unzip the deck, and open it in Podium. + +Controls from here are keyboard based: + +- CMD-Shift-P - Enter presentation mode; or, if in presentation mode, Pause timer +- CMD-P - Open presentation in Print view +- Esc - Exit presentation mode +- CMD-Tab - Switch displays +- Right/Left arrows - Next/previous slide +- Down/Up arrows - Next/previous slide +- Enter - Next slide +- Home/End - first/last slide +- CMD-A - Switch aspect ratio between 16:9 and 4:3 +- CMD-R - Reload slide deck +- CMD-T - Reset timer + +If you're on Linux, "CMD" is the Control key. + +## Developing Podium + +Podium uses the [BeeWare](https://beeware.org) suite of tools and libraries -most notably, the [Toga](https://github.com/beeware/toga) widget toolkit, and the [Briefcase](https://github.com/beeware/briefcase) packaging tool. + +To develop Podium, create a virtual environment, and install the BeeWare tools. + +Then, you can create a virtual environment and install the BeeWare tools: + + $ mkdir beeware + $ cd beeware + $ python3 -m venv venv + $ source venv/bin/activate + (venv) $ pip install briefcase + +Now that you have the code, you can clone the Podium repository and run it in developer mode: + + (venv) $ git clone https://github.com/beeware/podium.git + (venv) $ cd podium + (venv) $ briefcase dev + +This should open the same file dialog as before. + +### Packaging with Briefcase + +Use [Briefcase](https://github.com/beeware/briefcase) to package this repository as a standalone application: + + $ briefcase package + +Depending on your platform, this will produce a `macOS` folder containing a Podium DMG file, or a `linux` folder containing a system package appropriate to your distribution (a .deb, .rpm or .pkg.zip file) + +## Overriding Default themes + +Define a style.css file to override the default theme. You can use the **Debugging** section to help you create a theme that suites your style. + +## Debugging + +If you need to debug the CSS for a slide, you may want to use the "inspect element" feature of the webview. You may need to manually enable the feature at an operating system level: + +- **macOS**: at a terminal prompt, run: + + > defaults write org.beeware.podium WebKitDeveloperExtras -bool true + +## Documentation + +Documentation for Podium can be found on [Read The Docs](https://podium-app.readthedocs.io/en/latest/). + +## Community + +Podium is part of the [BeeWare suite](https://beeware.org). You can talk to the community through: + +- [@beeware@fosstodon.org on Mastodon](https://fosstodon.org/@beeware) +- [Discord](https://beeware.org/bee/chat/) + +We foster a welcoming and respectful community as described in our [BeeWare Community Code of Conduct](https://beeware.org/community/behavior/). + +## Contributing + +If you experience problems with Podium, [log them on GitHub](https://github.com/beeware/podium/issues). + +If you want to contribute, please [fork the project](https://github.com/beeware/podium) and [submit a pull request](https://github.com/beeware/podium/pulls). diff --git a/README.rst b/README.rst deleted file mode 100644 index d722b63..0000000 --- a/README.rst +++ /dev/null @@ -1,191 +0,0 @@ -.. image:: https://beeware.org/project/projects/applications/podium/podium.png - :width: 72px - :target: https://beeware.org/project/projects/applications/podium - -Podium -====== - -.. image:: https://img.shields.io/discord/836455665257021440?label=Discord%20Chat&logo=discord&style=plastic - :target: https://beeware.org/bee/chat/ - :alt: Discord server - -A markup-based slide presentation tool. - -Why? ----- - -Developers go to conferences. And when they do, they need slide decks. - -Unfortunately, while presentation tools like `Keynote`_ and `PowerPoint`_ -are great for business presentations, they aren't well suited to the -needs of developers. The mainstay of developer presentations -- code -samples -- are generally painful to add to a Keynote presentation. - -These presentation tools also come from a WYSIWYG (What You See Is What You -Get) tradition. This can be powerful, because it makes it easy to put -anything you want onto a slide. But it can also be painful, because you -end up spending all your time pushing pixels into the right place, instead -of focussing on the content of your talk. And if you want to make a style -change, you may need to apply that change manually to every slide. The lessons -of separating content from markup can't be applied to a WYSIWYG world. - -On top of all that, the document formats for Keynote and Powerpoint are -binary blobs -- they don't lend themselves to version control, collaborative -editing, and so on. - -The developer response to this has been to use HTML5. Recent years have seen -the development of a number of HTML-based presentation tools, like prezi_, -`deck.js`_, `keydown`_ and `showoff`_. These tools exploit the power of HTML5 -to make full screen presentations. - -However, by using browser technology as the basis for these tools, they miss -one very important feature of WYSIWYG presentation tools: presenter mode. -One of the big features of Keynote and Powerpoint is that they aren't just -decks of slides -- they have presenter notes and timing tools, and the -display shown to the audience isn't the same as the display shown to the -presenter. Web-based presentation tools are often missing presenter mode. - -Or, if they *do* have a presenter mode, they rely on you being able to -independently resize two separate web browsers, and they won't provide any -assistance in hiding all the browser toolbars, menus, titlebars, and so on. -This can be done, but it's awkward. - -Many of these tools are also online-only. They assume that you have a good WiFi -connection, and will be able to display your content live off the internet... -which if you've ever been to a developer conference, you'll know is a risky -proposition. - -Podium attempts to bridge the gap between these two poles. It is comprised of: - -* A simple, text-based markup format, focussed on the needs of developer - presentations. -* A graphical presentation tool that has a presenter display independent of - the slide display. - -.. _prezi: http://prezi.com -.. _deck.js: http://imakewebthings.com/deck.js/ -.. _keydown: https://github.com/infews/keydown -.. _showoff: https://github.com/drnic/showoff - -Quickstart ----------- - -Official releases of Podium can be downloaded from the `GitHub releases page -`__. - -Download the binary for your platform of choice, and run it. This should open a -file dialog, prompting you to open a ``.podium`` slide deck. An example Podium -slide deck is also available in the releases folder. Unzip the deck, and open -it in Podium. - -Controls from here are keyboard based: - -* CMD-Shift-P - Enter presentation mode; or, if in presentation mode, Pause timer -* CMD-P - Open presentation in Print view -* Esc - Exit presentation mode -* CMD-Tab - Switch displays -* Right/Left arrows - Next/previous slide -* Down/Up arrows - Next/previous slide -* Enter - Next slide -* Home/End - first/last slide -* CMD-A - Switch aspect ratio between 16:9 and 4:3 -* CMD-R - Reload slide deck -* CMD-T - Reset timer - -If you're on Linux, "CMD" is the Control key. - -Developing Podium ------------------ - -Podium uses the `BeeWare `__ suite of tools and libraries - -most notably, the `Toga `__ widget toolkit, and -the `Briefcase `__ packaging tool. - -To develop Podium, create a virtual environment, and install the BeeWare tools. - -If you're using Linux, you'll need to install some system packages first:: - - # Ubuntu/Debian - $ sudo apt-get update - $ sudo apt-get install python3-dev libgirepository2.0-dev libcairo2-dev libpango1.0-dev gir1.2-gtk-3.0 libcanberra-gtk3-module gir1.2-webkit2-4.1 dpkg-dev - - # Fedora - $ sudo dnf install pkg-config python3-devel gobject-introspection-devel cairo-devel gtk3 cairo-gobject-devel pango-devel libcanberra-gtk3 webkit2gtk4.1 rpm-build - - -Then, you can create a virtual environment and install the BeeWare tools:: - - $ mkdir beeware - $ cd beeware - $ python3 -m venv venv - $ source venv/bin/activate - (venv) $ pip install briefcase - -Now that you have the code, you can clone the Podium repository and run it in -developer mode:: - - (venv) $ git clone https://github.com/beeware/podium.git - (venv) $ cd podium - (venv) $ briefcase dev - -This should open the same file dialog as before. - -Packaging with Briefcase -~~~~~~~~~~~~~~~~~~~~~~~~ - -Use `Briefcase`_ to package this repository as a standalone application:: - - $ briefcase package - -Depending on your platform, this will produce a ``macOS`` folder containing a -Podium DMG file, or a ``linux`` folder containing a system package appropriate -to your distribution (a `.deb`, `.rpm` or `.pkg.zip` file) - -Overriding Default themes -------------------------- - -Define a `style.css` file to override the default theme. You can use the -**Debugging** section to help you create a theme that suites your style. - -Debugging ---------- - -If you need to debug the CSS for a slide, you may want to use the "inspect -element" feature of the webview. You may need to manually enable the -feature at an operating system level: - -* **macOS**: at a terminal prompt, run: - - defaults write org.beeware.podium WebKitDeveloperExtras -bool true - -Documentation -------------- - -Documentation for Podium can be found on `Read The Docs`_. - -Community ---------- - -Podium is part of the `BeeWare suite `__. You can talk to the -community through: - -* `@beeware@fosstodon.org on Mastodon `__ - -* `Discord `__ - -We foster a welcoming and respectful community as described in our `BeeWare Community -Code of Conduct `__. - -Contributing ------------- - -If you experience problems with Podium, `log them on GitHub `__. - -If you want to contribute, please `fork the project `__ and `submit a pull request `__. - - -.. _BeeWare suite: https://beeware.org/ -.. _Keynote: https://en.wikipedia.org/wiki/Keynote_(presentation_software) -.. _PowerPoint: https://en.wikipedia.org/wiki/Microsoft_PowerPoint -.. _Briefcase: https://github.com/beeware/briefcase -.. _Read The Docs: https://podium-app.readthedocs.io/en/latest/ diff --git a/changes/91.doc.md b/changes/91.doc.md new file mode 100644 index 0000000..c8dba3a --- /dev/null +++ b/changes/91.doc.md @@ -0,0 +1 @@ +Documentation now using MkDocs. diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 11d424e..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,153 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/podium.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/podium.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/podium" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/podium" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index c857a23..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,242 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Podium documentation build configuration file, created by -# sphinx-quickstart on Sat Jul 27 14:58:42 2013. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Podium' -copyright = u'2013, Russell Keith-Magee' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.1' -# The full version, including alpha/beta/rc tags. -release = '0.1' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'podiumdoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'podium.tex', u'Podium Documentation', - u'Russell Keith-Magee', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'podium', u'Podium Documentation', - [u'Russell Keith-Magee'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'podium', u'Podium Documentation', - u'Russell Keith-Magee', 'Podium', 'A presentation tool for developers.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' \ No newline at end of file diff --git a/docs/config.yml b/docs/config.yml new file mode 100644 index 0000000..c85059b --- /dev/null +++ b/docs/config.yml @@ -0,0 +1,132 @@ +copyright: © Russell Keith-Magee + + +not_in_nav: index.md + +validation: + omitted_files: warn + absolute_links: relative_to_docs + anchors: warn + unrecognized_links: warn + +extra: + project_name: podium + formal_name: Podium + min_python_version: "3.10" # The oldest supported Python version + min_python_version_tag: "310" # The tag version of the minimum python version + recent_python_version: "3.14" # The newest Python version known to work on all platforms + docs_python_version: "3.13" # The version of Python required to build the documentation + contribution_guide_root: how-to/contribute + social: + - icon: fontawesome/brands/github + link: https://github.com/beeware + name: BeeWare on GitHub + - icon: fontawesome/brands/mastodon + link: https://fosstodon.org/@beeware + name: BeeWare on Mastodon + - icon: fontawesome/brands/discord + link: https://beeware.org/bee/chat/ + name: BeeWare on Discord + generator: false + +theme: + name: material + language: en + logo: images/podium.png + favicon: images/podium.png + features: + - content.tabs.link + - toc.follow + - navigation.tabs + - navigation.tabs.sticky + - navigation.indexes + - navigation.footer + - search.suggest + - search.highlight + - search.share + custom_dir: overrides + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to system preference + +markdown_extensions: + # PyMdown Extensions + pymdownx.caret: {} + pymdownx.highlight: {} + pymdownx.superfences: {} + pymdownx.blocks.caption: {} + pymdownx.blocks.admonition: # Enables admonitions. + types: + - note + - abstract + - info + - tip + - success + - question + - warning + - failure + - danger + - bug + - example + - quote + pymdownx.blocks.details: # Enables collapsible content. + types: + - {name: details-note, class: note} + - {name: details-abstract, class: abstract} + - {name: details-info, class: info} + - {name: details-tip, class: tip} + - {name: details-success, class: success} + - {name: details-question, class: question} + - {name: details-warning, class: warning} + - {name: details-failure, class: failure} + - {name: details-danger, class: danger} + - {name: details-bug, class: bug} + - {name: details-example, class: example} + - {name: details-quote, class: quote} + pymdownx.magiclink: # Among other things, enables GitHub shorthand references. + provider: "github" + user: "beeware" + repo: "podium" + repo_url_shortener: true + repo_url_shorthand: true + normalize_issue_symbols: true + pymdownx.blocks.tab: + alternate_style: true + pymdownx.snippets: + base_path: ["docs/en", "examples"] + url_download: true + check_paths: true + # Python Markdown Extensions + attr_list: {} + footnotes: {} + md_in_html: {} + smarty: # Enables easy em and en dashes. + smart_quotes: false + toc: + permalink: true + title: On this page + +plugins: + search: {} + autorefs: + resolve_closest: true # autorefs warns of the Usage headings being duplicates without this - we will have to assign unique ids to all of them otherwise + literate-nav: + nav_file: SUMMARY.md + macros: {} diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md new file mode 100644 index 0000000..256ecbc --- /dev/null +++ b/docs/en/SUMMARY.md @@ -0,0 +1,43 @@ + + + + +- [Tutorial](tutorial/index.md) +- [How-to guides](how-to/index.md) + - [Contributing to Podium](how-to/contribute/index.md) + - [First-time contributors](how-to/contribute/first-time-contributors.md) + - What can I do? + - [Fix an issue](how-to/contribute/what/fix-issue.md) + - [Implement a new feature](how-to/contribute/what/implement-feature.md) + - [Write documentation](how-to/contribute/what/write-docs.md) + - [Triage an issue](how-to/contribute/what/triage.md) + - [Review a pull request](how-to/contribute/what/review-pr.md) + - [Propose a new feature](how-to/contribute/what/propose-feature.md) + - [Use the tools](how-to/contribute/what/use-tools.md) + - How do I contribute? + - [Setting up a development environment](how-to/contribute/how/dev-environment.md) + - [Reproducing an issue](how-to/contribute/how/reproduce-issue.md) + - [Working from a branch](how-to/contribute/how/branches.md) + - [Avoiding scope creep](how-to/contribute/how/scope-creep.md) + - [Writing, running, and testing code](how-to/contribute/how/write-code.md) + - [Building documentation](how-to/contribute/how/build-docs.md) + - [Writing documentation](how-to/contribute/how/write-docs.md) + - [Adding a change note](how-to/contribute/how/change-note.md) + - [Submitting a pull request](how-to/contribute/how/submit-pr.md) + - [Providing a review](how-to/contribute/how/review-pr.md) + - [Submitting a new issue](how-to/contribute/how/new-issue.md) + - [Proposing a new feature](how-to/contribute/how/propose-feature.md) + - What happens next? + - [Pull request review process](how-to/contribute/next/pr-review.md) + - [Release process](how-to/contribute/next/release.md) + - Policies + - [AI Policy](how-to/contribute/policies/ai-policy.md) + - Style guides + - [Code style guide](how-to/contribute/style/code-style-guide.md) + - [Documentation style guide](how-to/contribute/style/docs-style-guide.md) +- [Reference](reference/index.md) +- [About](about/index.md) + - [Why Podium?](about/why.md) + - [Presentation demos](about/demos.md) + - [Roadmap](about/roadmap.md) + - [Releases](about/releases.md) diff --git a/docs/en/about/demos.md b/docs/en/about/demos.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/en/about/index.md b/docs/en/about/index.md new file mode 100644 index 0000000..fdc2f91 --- /dev/null +++ b/docs/en/about/index.md @@ -0,0 +1,8 @@ +# About Podium + +Want to know more about the Podium project, its history, and plans for the future? That's what you'll find here! + +* [Why Podium?](why.md) - The purpose and concepts behind the choice to create Podium. +* [Presentation demos](demos.md) - Examples of presentations built with Podium. +* [Release history](releases.md) - A list of changes made in each release. +* [Podium's road map](roadmap.md) - Future plans for Podium. diff --git a/docs/en/about/releases.md b/docs/en/about/releases.md new file mode 100644 index 0000000..cb4d037 --- /dev/null +++ b/docs/en/about/releases.md @@ -0,0 +1,19 @@ +# Release History + + + + + +## v0.3.0 (in development) + +- Updated to use Toga 0.5.4, and new Document-based app structure +- Added support for Windows, and corrected many bugs on Linux. +- Modified the "stop slideshow" shortcut to CMD-S/Alt-S + +## v0.2 (2 Jan 2020) + +- First formal release. Includes macOS and Linux support. + +## 0.1.0 + +- Initial public release. diff --git a/docs/en/about/roadmap.md b/docs/en/about/roadmap.md new file mode 100644 index 0000000..bd29e84 --- /dev/null +++ b/docs/en/about/roadmap.md @@ -0,0 +1,13 @@ +# The Podium development roadmap + +TODO: Needs intro. + +In the short term, features we'd like to add include: + +- timing estimates based on speaker notes +- an in-app slide editor +- themes, stylesheets, and branding for slides +- the ability to produce a PDF of a slide deck +- the ability to publish a slide deck or collection thereof as a website. + +For a comprehensive list of features we'd like to add, see the [enhancements issue list on GitHub](https://github.com/beeware/podium/issues?q=is%3Aissue%20state%3Aopen%20label%3Aenhancement). diff --git a/docs/en/about/why.md b/docs/en/about/why.md new file mode 100644 index 0000000..45beed5 --- /dev/null +++ b/docs/en/about/why.md @@ -0,0 +1,24 @@ +# Why Podium? + +Developers go to conferences. And when they do, they need slide decks. + +Unfortunately, while presentation tools like [Keynote](https://en.wikipedia.org/wiki/Keynote_(presentation_software)) and [PowerPoint](https://en.wikipedia.org/wiki/Microsoft_PowerPoint) are great for business presentations, they aren't well suited to the needs of developers. The mainstay of developer presentations -- code samples -- are generally painful to add to a Keynote presentation. + +These presentation tools also come from a WYSIWYG (What You See Is What You Get) tradition. This can be powerful, because it makes it easy to put anything you want onto a slide. But it can also be painful, because you end up spending all your time pushing pixels into the right place, instead of focussing on the content of your talk. And if you want to make a style change, you may need to apply that change manually to every slide. The lessons of separating content from markup can't be applied to a WYSIWYG world. + +On top of all that, the document formats for Keynote and PowerPoint are binary blobs -- they don't lend themselves to version control, collaborative editing, and so on. + +The developer response to this has been to use HTML5. Recent years have seen the development of a number of HTML-based presentation tools, like [prezi](http://prezi.com), [deck.js](http://imakewebthings.com/deck.js/), [keydown](https://github.com/infews/keydown), [reveal.js](https://reveal.js) and [showoff](https://github.com/drnic/showoff). These tools exploit the power of HTML5 to make full screen presentations. + +However, by using browser technology as the basis for these tools, they miss one very important feature of WYSIWYG presentation tools: presenter mode. One of the big features of Keynote and PowerPoint is that they aren't just decks of slides -- they have presenter notes and timing tools, and the display shown to the audience isn't the same as the display shown to the presenter. Web-based presentation tools are often missing presenter mode. + +Or, if they *do* have a presenter mode, they rely on you being able to independently resize two separate web browsers, and they won't provide any assistance in hiding all the browser toolbars, menus, titlebars, and so on. This can be done, but it's awkward. + +Many of these tools are also online-only. They assume that you have a good Wi-Fi connection, and will be able to display your content live off the internet... which if you've ever been to a developer conference, you'll know is a risky proposition. + +Podium attempts to bridge the gap between these two poles. It is comprised of: + +- A simple, text-based markup format, focussed on the needs of developer + presentations. +- A graphical presentation tool that has a presenter display independent + of the slide display. diff --git a/docs/en/how-to/contribute/first-time-contributors.md b/docs/en/how-to/contribute/first-time-contributors.md new file mode 100644 index 0000000..04a4572 --- /dev/null +++ b/docs/en/how-to/contribute/first-time-contributors.md @@ -0,0 +1,3 @@ +# First-time contributors + +{% extends "_shared/contribute/first-time-contributors.md" %} diff --git a/docs/en/how-to/contribute/how/branches.md b/docs/en/how-to/contribute/how/branches.md new file mode 100644 index 0000000..88d2da3 --- /dev/null +++ b/docs/en/how-to/contribute/how/branches.md @@ -0,0 +1,3 @@ +# Work from a feature branch, not your `main` branch + +{% extends "_shared/contribute/how/branches.md" %} diff --git a/docs/en/how-to/contribute/how/build-docs.md b/docs/en/how-to/contribute/how/build-docs.md new file mode 100644 index 0000000..7755ef9 --- /dev/null +++ b/docs/en/how-to/contribute/how/build-docs.md @@ -0,0 +1,15 @@ +# Building documentation + +{% extends "_shared/contribute/how/build-docs.md" %} + +{% block front_matter %} + +Before you build the documentation, and have a [development environment](../how/dev-environment.md) set up. + +{% endblock %} + +{% block end_matter %} + +Once you have successfully built the docs, you are ready to [write documentation](../how/write-docs.md). + +{% endblock %} diff --git a/docs/en/how-to/contribute/how/change-note.md b/docs/en/how-to/contribute/how/change-note.md new file mode 100644 index 0000000..f499d90 --- /dev/null +++ b/docs/en/how-to/contribute/how/change-note.md @@ -0,0 +1,3 @@ +# Adding change information for release notes + +{% extends "_shared/contribute/how/change-note.md" %} diff --git a/docs/en/how-to/contribute/how/dev-environment.md b/docs/en/how-to/contribute/how/dev-environment.md new file mode 100644 index 0000000..2f2e106 --- /dev/null +++ b/docs/en/how-to/contribute/how/dev-environment.md @@ -0,0 +1,3 @@ +# Setting up a development environment + +{% extends "_shared/contribute/how/dev-environment.md" %} diff --git a/docs/en/how-to/contribute/how/new-issue.md b/docs/en/how-to/contribute/how/new-issue.md new file mode 100644 index 0000000..30f3f0c --- /dev/null +++ b/docs/en/how-to/contribute/how/new-issue.md @@ -0,0 +1,3 @@ +# Submitting a new issue + +{% extends "_shared/contribute/how/new-issue.md" %} diff --git a/docs/en/how-to/contribute/how/propose-feature.md b/docs/en/how-to/contribute/how/propose-feature.md new file mode 100644 index 0000000..cd27489 --- /dev/null +++ b/docs/en/how-to/contribute/how/propose-feature.md @@ -0,0 +1,9 @@ +# Proposing a new feature + +{% extends "_shared/contribute/how/propose-feature.md" %} + +{% block end_matter %} + +If you are interested, you can begin [implementing your new feature](../what/implement-feature.md). + +{% endblock %} diff --git a/docs/en/how-to/contribute/how/reproduce-issue.md b/docs/en/how-to/contribute/how/reproduce-issue.md new file mode 100644 index 0000000..e765196 --- /dev/null +++ b/docs/en/how-to/contribute/how/reproduce-issue.md @@ -0,0 +1,15 @@ +# Reproducing an issue + +{% extends "_shared/contribute/how/reproduce-issue.md" %} + +{% block front_matter %} + +To begin reproducing an issue, you will need a [development environment](../how/dev-environment.md) set up. + +{% endblock %} + +{% block end_matter %} + +At this point, you might choose to try to [fix the issue](../what/fix-issue.md) you've just reproduced; alternatively, you can write up your findings and try to reproduce another issue. + +{% endblock %} diff --git a/docs/en/how-to/contribute/how/review-pr.md b/docs/en/how-to/contribute/how/review-pr.md new file mode 100644 index 0000000..30e8d2f --- /dev/null +++ b/docs/en/how-to/contribute/how/review-pr.md @@ -0,0 +1,3 @@ +# Providing a pull request review + +{% extends "_shared/contribute/how/review-pr.md" %} diff --git a/docs/en/how-to/contribute/how/scope-creep.md b/docs/en/how-to/contribute/how/scope-creep.md new file mode 100644 index 0000000..22718a3 --- /dev/null +++ b/docs/en/how-to/contribute/how/scope-creep.md @@ -0,0 +1,3 @@ +# Avoiding scope creep + +{% extends "_shared/contribute/how/scope-creep.md" %} diff --git a/docs/en/how-to/contribute/how/submit-pr.md b/docs/en/how-to/contribute/how/submit-pr.md new file mode 100644 index 0000000..5937a49 --- /dev/null +++ b/docs/en/how-to/contribute/how/submit-pr.md @@ -0,0 +1,17 @@ +# Submitting a pull request + +{% extends "_shared/contribute/how/submit-pr.md" %} + +{% block end_matter %} + +{% if config.extra.website %} + +Your pull request may require additional content, such as a [change note](../how/change-note.md), before it can be [reviewed](../next/pr-review.md). + +{% else %} + +As part of submitting a pull request, you'll need to include a [change note](../how/change-note.md) before it can be [reviewed](../next/pr-review.md). + +{% endif %} + +{% endblock %} diff --git a/docs/en/how-to/contribute/how/write-code.md b/docs/en/how-to/contribute/how/write-code.md new file mode 100644 index 0000000..a167a69 --- /dev/null +++ b/docs/en/how-to/contribute/how/write-code.md @@ -0,0 +1,15 @@ +# Writing, running, and testing code + +{% extends "_shared/contribute/how/write-code.md" %} + +{% block front_matter %} + +To begin working on code, ensure you have a [development environment](../how/dev-environment.md) set up, and you are [working on a branch](../how/branches.md) + +{% endblock %} + +{% block end_matter %} + +Once you have everything working, you can [submit a pull request](../how/submit-pr.md) with your changes. + +{% endblock %} diff --git a/docs/en/how-to/contribute/how/write-docs.md b/docs/en/how-to/contribute/how/write-docs.md new file mode 100644 index 0000000..146b398 --- /dev/null +++ b/docs/en/how-to/contribute/how/write-docs.md @@ -0,0 +1,15 @@ +# Writing documentation + +{% extends "_shared/contribute/how/write-docs.md" %} + +{% block front_matter %} + +Before you begin writing documentation, ensure you are able to [build the documentation](../how/build-docs.md), and you are [working on a branch](../how/branches.md). + +{% endblock %} + +{% block end_matter %} + +Once you are happy with your new documentation, you can [submit a pull request](../how/submit-pr.md) with your proposed changes. + +{% endblock %} diff --git a/docs/en/how-to/contribute/index.md b/docs/en/how-to/contribute/index.md new file mode 100644 index 0000000..e828b1f --- /dev/null +++ b/docs/en/how-to/contribute/index.md @@ -0,0 +1,3 @@ +# Contributing to {{ formal_name }} + +{% extends "_shared/contribute/index.md" %} diff --git a/docs/en/how-to/contribute/next/pr-review.md b/docs/en/how-to/contribute/next/pr-review.md new file mode 100644 index 0000000..65cfdfc --- /dev/null +++ b/docs/en/how-to/contribute/next/pr-review.md @@ -0,0 +1,3 @@ +# Receiving a pull request review + +{% extends "_shared/contribute/next/pr-review.md" %} diff --git a/docs/en/how-to/contribute/next/release.md b/docs/en/how-to/contribute/next/release.md new file mode 100644 index 0000000..44a7772 --- /dev/null +++ b/docs/en/how-to/contribute/next/release.md @@ -0,0 +1,3 @@ +# The release process + +{% extends "_shared/contribute/next/release.md" %} diff --git a/docs/en/how-to/contribute/policies/ai-policy.md b/docs/en/how-to/contribute/policies/ai-policy.md new file mode 100644 index 0000000..3e9364b --- /dev/null +++ b/docs/en/how-to/contribute/policies/ai-policy.md @@ -0,0 +1,3 @@ + + +{% extends "_shared/contribute/policies/ai-policy.md" %} diff --git a/docs/en/how-to/contribute/style/code-style-guide.md b/docs/en/how-to/contribute/style/code-style-guide.md new file mode 100644 index 0000000..43f8d1f --- /dev/null +++ b/docs/en/how-to/contribute/style/code-style-guide.md @@ -0,0 +1,3 @@ +# Code style guide + +{% extends "_shared/contribute/style/code-style-guide.md" %} diff --git a/docs/en/how-to/contribute/style/docs-style-guide.md b/docs/en/how-to/contribute/style/docs-style-guide.md new file mode 100644 index 0000000..5164a0a --- /dev/null +++ b/docs/en/how-to/contribute/style/docs-style-guide.md @@ -0,0 +1,3 @@ +# Documentation style guide + +{% extends "_shared/contribute/style/docs-style-guide.md" %} diff --git a/docs/en/how-to/contribute/what/fix-issue.md b/docs/en/how-to/contribute/what/fix-issue.md new file mode 100644 index 0000000..8cdb8bf --- /dev/null +++ b/docs/en/how-to/contribute/what/fix-issue.md @@ -0,0 +1,3 @@ +# Fixing an issue + +{% extends "_shared/contribute/what/fix-issue.md" %} diff --git a/docs/en/how-to/contribute/what/implement-feature.md b/docs/en/how-to/contribute/what/implement-feature.md new file mode 100644 index 0000000..c1ecd28 --- /dev/null +++ b/docs/en/how-to/contribute/what/implement-feature.md @@ -0,0 +1,3 @@ +# Implementing a new feature + +{% extends "_shared/contribute/what/implement-feature.md" %} diff --git a/docs/en/how-to/contribute/what/propose-feature.md b/docs/en/how-to/contribute/what/propose-feature.md new file mode 100644 index 0000000..c815205 --- /dev/null +++ b/docs/en/how-to/contribute/what/propose-feature.md @@ -0,0 +1,3 @@ +# Proposing a new feature + +{% extends "_shared/contribute/what/propose-feature.md" %} diff --git a/docs/en/how-to/contribute/what/review-pr.md b/docs/en/how-to/contribute/what/review-pr.md new file mode 100644 index 0000000..9c4b9f8 --- /dev/null +++ b/docs/en/how-to/contribute/what/review-pr.md @@ -0,0 +1,3 @@ +# Providing a pull request review + +{% extends "_shared/contribute/what/review-pr.md" %} diff --git a/docs/en/how-to/contribute/what/triage.md b/docs/en/how-to/contribute/what/triage.md new file mode 100644 index 0000000..ead5509 --- /dev/null +++ b/docs/en/how-to/contribute/what/triage.md @@ -0,0 +1,3 @@ +# Triaging an issue + +{% extends "_shared/contribute/what/triage.md" %} diff --git a/docs/en/how-to/contribute/what/use-tools.md b/docs/en/how-to/contribute/what/use-tools.md new file mode 100644 index 0000000..cc77532 --- /dev/null +++ b/docs/en/how-to/contribute/what/use-tools.md @@ -0,0 +1,3 @@ +# Using the tools + +{% extends "_shared/contribute/what/use-tools.md" %} diff --git a/docs/en/how-to/contribute/what/write-docs.md b/docs/en/how-to/contribute/what/write-docs.md new file mode 100644 index 0000000..3be56fe --- /dev/null +++ b/docs/en/how-to/contribute/what/write-docs.md @@ -0,0 +1,3 @@ +# Adding documentation + +{% extends "_shared/contribute/what/write-docs.md" %} diff --git a/docs/en/how-to/index.md b/docs/en/how-to/index.md new file mode 100644 index 0000000..6efb80a --- /dev/null +++ b/docs/en/how-to/index.md @@ -0,0 +1,7 @@ +# How-to guides + +How-to guides are recipes that take the user through steps in key subjects. They are more advanced than tutorials and assume a lot more about what the user already knows than tutorials do, and unlike documents in the tutorial they can stand alone. + +## [Contributing to Podium](contribute/index.md) + +* [Contributing to Podium](contribute/index.md) - The many ways you can contribute to Podium, including what you can do and how to do it. diff --git a/docs/en/images/show_package_contents.png b/docs/en/images/show_package_contents.png new file mode 100644 index 0000000..d38445e Binary files /dev/null and b/docs/en/images/show_package_contents.png differ diff --git a/docs/en/images/slide_view_window.png b/docs/en/images/slide_view_window.png new file mode 100644 index 0000000..7289e29 Binary files /dev/null and b/docs/en/images/slide_view_window.png differ diff --git a/docs/en/images/speaker_view_window.png b/docs/en/images/speaker_view_window.png new file mode 100644 index 0000000..5d3076d Binary files /dev/null and b/docs/en/images/speaker_view_window.png differ diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 0000000..a2de221 --- /dev/null +++ b/docs/en/index.md @@ -0,0 +1,43 @@ +# Podium + +A presentation tool for developers. + +## [Tutorial](tutorial/index.md) + +Get started with a hands-on introduction for beginners. + +## [How-to guides](how-to/index.md) + +Guides on how to contribute. + + + +## [Reference](reference/index.md) + +Slide syntax guide and keyboard shortcuts. + +## [About Podium](about/index.md) + +The reason behind Podium, and other details about the project. + +## Community + +Podium is part of the [BeeWare suite](https://beeware.org). You can talk to the community through: + +- [@beeware@fosstodon.org on Mastodon](https://fosstodon.org/@beeware) +- [Discord](https://beeware.org/bee/chat/) +- The Podium [GitHub Discussions forum](https://github.com/beeware/podium/discussions) + +### Code of Conduct + +The BeeWare community has a strict [Code of Conduct](https://beeware.org/community/code-of-conduct/). All users and developers are expected to adhere to this code. + +If you have any concerns about this code of conduct, or you wish to report a violation of this code, please contact the [Code of Conduct Response Team](mailto:conduct@beeware.org). + +### Contributing + +If you experience problems with Podium, [log them on GitHub](https://github.com/beeware/Podium/issues). If you want to contribute to Podium, you can read through the [Podium contribution guides](how-to/contribute/index.md). diff --git a/docs/en/reference/index.md b/docs/en/reference/index.md new file mode 100644 index 0000000..a4f0b9c --- /dev/null +++ b/docs/en/reference/index.md @@ -0,0 +1,23 @@ +# Podium reference + +TODO: Intro + +## Syntax + +### Title slide + +### Bullet slides + +## Keyboard shortcuts + +- CMD-Shift-P - Enter presentation mode; or, if in presentation mode, Pause timer +- CMD-P - Open presentation in Print view +- CMD-Q - Quit Podium (exit presentation mode) +- CMD-Tab - Switch displays +- Right/Left arrows - Next/previous slide +- Down/Up arrows - Next/previous slide +- Enter - Next slide +- Home/End - first/last slide +- CMD-A - Switch aspect ratio between 16:9 and 4:3 +- CMD-R - Reload slide deck +- CMD-T - Reset timer diff --git a/docs/en/tutorial/index.md b/docs/en/tutorial/index.md new file mode 100644 index 0000000..90595b3 --- /dev/null +++ b/docs/en/tutorial/index.md @@ -0,0 +1,90 @@ +# Podium tutorial + +This tutorial will get you started using Podium. + +## Downloading Podium + +The first step is to clone a copy of the Podium repository onto your computer. + +Run the following commands: + +```console +$ git clone https://github.com/beeware/podium.git +$ cd podium +``` + +This puts you in the `podium` directory. You are now ready to run Podium. + +## Running Podium + +The most straightforward way to run Podium, is using `uv`. You'll need to [install `uv`](https://docs.astral.sh/uv/getting-started/installation/) first. + +Podium requires Python 3.12 or newer. You will need to have 3.12 or newer installed, and you will need to know which version within that requirement you are specifically using. + +To open Podium, run the following: + +```console +$ uvx -p 3.XX briefcase run +``` + +where `3.XX` is your version of Python. For example, if you have installed and are using Python 3.14, you would run the following: + +```console +$ uvx -p 3.14 briefcase run +``` + +You will see something like the following: + +```text +Installed 44 packages in 113ms +Evaluating dynamic project metadata... done + +[podium] Starting app... +=========================================================================== +Starting server... +Serving on 127.0.0.1:49856 +``` + +The port number (the number after the colon on the `Serving on` line) will be different each time. + +This will generate a file-open dialog. + +## Opening the slide deck + +In the dialog window, navigate to the `examples` directory and choose `example.podium`. + +This opens two windows. + +- The slide view window: + +![The slide view window in Podium with the example slide deck open.](../images/slide_view_window.png) + +- The speaker view window: + +![The speaker view window in Podium with the example slide deck open.](../images/speaker_view_window.png) + +You are now ready to begin editing the slides. + +## Editing the slides + +Open Finder, and navigate to the `examples` directory. Right-click on the `example.podium` bundle, and choose "Show Package Contents". + +![The context menu for the `example.podium` slide deck bundle.](../images/show_package_contents.png) + +/// caption + +/// + +Within the `example.podium` bundle, you'll find the following files: + +```text +example.podium/ +├── slides.md +├── style.css +├── slides.htmls +├── screenshot.png +├── kitten.png +└── beeware.png +``` + +Open `slides.md` in your favorite Markdown editor. The example slide deck contains demos of pretty much everything Podium can do, including various formatting, incremental slide builds, code samples, and several animated transitions. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 193e6c9..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,83 +0,0 @@ -Podium -====== - -A presentation tool for developers. - -Quickstart ----------- - -In your virtualenv, install Podium, and then run it:: - - $ pip install podium - $ podium - -This will pop up a GUI window. - -Problems under Ubuntu/Debian -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Debian and Ubuntu's packaging of Python omits the ``idlelib`` library from it's -base packge. If you're using Python 2.7 on Ubuntu 13.04, you can install -``idlelib`` by running:: - - $ sudo apt-get install idle-python2.7 - -For other versions of Python, Ubuntu and Debian, you'll need to adjust this as -appropriate. - -Problems under Windows -~~~~~~~~~~~~~~~~~~~~~~ - -If you're running Podium in a virtualenv, you'll need to set an -environment variable so that Podium can find the TCL graphics library:: - - $ set TCL_LIBRARY=c:\Python27\tcl\tcl8.5 - -You'll need to adjust the exact path to reflect your local Python install. -You may find it helpful to put this line in the ``activate.bat`` script -for your virtual environment so that it is automatically set whenever the -virtualenv is activated. - -Documentation -------------- - -Documentation for Podium can be found on `Read The Docs `__. - -Community ---------- - -Podium is part of the `BeeWare suite `__. You can talk to the -community through: - -* `@beeware@fosstodon.org on Mastodon `__ - -* `Discord `__ - -We foster a welcoming and respectful community as described in our `BeeWare Community -Code of Conduct `__. - -Contributing ------------- - -If you experience problems with Podium, `log them on GitHub `__. - -If you want to contribute, please `fork the project `__ and `submit a pull request `__. - - -Contents: - -.. toctree:: - :maxdepth: 2 - :glob: - - internals/contributing - internals/roadmap - releases - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/internals/contributing.rst b/docs/internals/contributing.rst deleted file mode 100644 index cb8eccc..0000000 --- a/docs/internals/contributing.rst +++ /dev/null @@ -1,42 +0,0 @@ -Contributing to Podium -====================== - - -If you experience problems with Podium, `log them on GitHub`_. If you want to contribute code, -please `fork the code`_ and `submit a pull request`_. - -.. _log them on Github: https://github.com/pybee/podium/issues -.. _fork the code: https://github.com/pybee/podium -.. _submit a pull request: https://github.com/pybee/podium/pulls - - -Setting up your development environment ---------------------------------------- - -Install prerequisites -~~~~~~~~~~~~~~~~~~~~~ - -Podium requires Toga_ (A Python native, OS native GUI toolkit). -Follow the instructions to install `Toga Prerequisites`_ for your operating system. - -Setup virtual environment and install Podium -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The recommended way of setting up your development environment for Podium -is to create a virtual environment, install Podium in development mode into -your virtual environment and start coding. -Assuming that you are using ``virtualenvwrapper``, you only have to run:: - - $ git clone https://github.com/beeware/podium.git - $ cd podium - $ mkvirtualenv podium - $ pip install -e . - - -Podium uses ``unittest`` for its own test suite as well as additional helper -modules for testing. - -Now you are ready to start hacking! Have fun! - -.. _Toga: https://github.com/beeware/toga -.. _Toga Prerequisites: https://github.com/beeware/toga#prerequisites diff --git a/docs/internals/roadmap.rst b/docs/internals/roadmap.rst deleted file mode 100644 index ab2775e..0000000 --- a/docs/internals/roadmap.rst +++ /dev/null @@ -1,7 +0,0 @@ -Podium Roadmap -============== - -Podium is a new project - we have lots of things that we'd like to do. If -you'd like to contribute, providing a patch for one of these features: - -* TBD diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 7857686..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,190 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -set I18NSPHINXOPTS=%SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Trebuchet.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Trebuchet.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end \ No newline at end of file diff --git a/docs/mkdocs.en.yml b/docs/mkdocs.en.yml new file mode 100644 index 0000000..bbfe2c0 --- /dev/null +++ b/docs/mkdocs.en.yml @@ -0,0 +1,10 @@ +INHERIT: config.yml +site_name: Podium +site_url: https://podium.beeware.org/ +docs_dir: en + +theme: + language: en + +extra: + header: {} diff --git a/docs/releases.rst b/docs/releases.rst deleted file mode 100644 index eb4f3fa..0000000 --- a/docs/releases.rst +++ /dev/null @@ -1,17 +0,0 @@ -Release History -=============== - -0.3.0 - In Development ----------------------- - -TBD - -0.2.0 ------ - -Initial binary release. - -0.1.0 ------ - -Initial public release. diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist new file mode 100644 index 0000000..e69de29 diff --git a/examples/example.podium/slides.md b/examples/example.podium/slides.md index 004e556..3d1b81f 100644 --- a/examples/example.podium/slides.md +++ b/examples/example.podium/slides.md @@ -5,9 +5,9 @@ class: title ??? -These are the speakers notes. They let the speaker know what they need to know. All work an no play makes jack a dull boy. +These are the speakers notes. They let the speaker know what they need to know. All work and no play makes jack a dull boy. -All work an no play makes jack a dull boy. All work an no play makes jack a dull boy. All work an no play makes jack a dull boy. All work an no play makes jack a dull boy. All work an no play makes jack a dull boy. +All work and no play makes jack a dull boy. All work and no play makes jack a dull boy. All work and no play makes jack a dull boy. All work and no play makes jack a dull boy. All work and no play makes jack a dull boy. --- @@ -130,14 +130,14 @@ class: logo ```python def greeting(arg): if arg == 'hello': - print 'Hello World' + print('Hello World') else: - print arg + print(arg) -class Something(object): +class Something(): def __init__(self, *args, **kwargs): - super(Something, self).__init__(*args, **kwargs) + super().__init__(*args, **kwargs) ``` @@ -191,7 +191,7 @@ It will then start a new paragraph. ```python def greeting(arg): if arg == 'hello': - print 'Hello World' + print('Hello World') ``` --- # Other inline content diff --git a/icons/podium-deck.ico b/icons/podium-deck.ico new file mode 100644 index 0000000..59bd65e Binary files /dev/null and b/icons/podium-deck.ico differ diff --git a/icons/podium-deck.png b/icons/podium-deck.png new file mode 100644 index 0000000..c720c3d Binary files /dev/null and b/icons/podium-deck.png differ diff --git a/icons/podium.ico b/icons/podium.ico new file mode 100644 index 0000000..f317824 Binary files /dev/null and b/icons/podium.ico differ diff --git a/pyproject.toml b/pyproject.toml index 857b1b1..bc9e652 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta" [project] dynamic = ["version"] name = "podium" -requires-python = "~=3.14" +requires-python = ">=3.12" # Temporary workaround for beeware/toga#4446 dependencies = ["packaging"] @@ -40,11 +40,10 @@ dev = [ test = [ {include-group = "setuptools-scm"}, ] -# Docs are always built on a specific Python version; see RTD and tox config files, -# and the docs contribution guide. + docs = [ - "beeware-docs-tools @ git+https://github.com/beeware/beeware-docs-tools", - # "beeware-docs-tools @ file://../beeware-docs-tools", + "beeware-docs-tools @ git+https://github.com/beeware/beeware-docs-tools", +# "beeware-docs-tools @ file://../beeware-docs-tools", ] [tool.briefcase] @@ -54,7 +53,7 @@ license-files = ["LICENSE"] bundle = "org.beeware" author = 'Russell Keith-Magee' author_email = 'russell@keith-magee.com' -homepage = 'https://beeware.org/project/projects/applications/podium' +homepage = 'https://podium.beeware.org' [tool.briefcase.app.podium] formal_name = "Podium" @@ -70,7 +69,7 @@ icon = "icons/podium" description = "Podium Slide Deck" extension = "podium" icon = "icons/podium-deck" -url = 'https://beeware.org/project/projects/applications/podium/' +url = 'https://podium.beeware.org' macOS.UTTypeConformsTo = ["com.apple.package", "public.content"] [tool.briefcase.app.podium.macOS] @@ -210,6 +209,38 @@ extend-select = [ [tool.ruff.lint.isort] combine-as-imports = true +[tool.rumdl] +flavor = "mkdocs" +include = ["**/*.md"] +exclude = [ + "comment.md", + "CODE_OF_CONDUCT.md", + "examples/example.podium/slides.md", + "changes/*.md", +] +respect-gitignore = true + +# Disable rules: +# MD014: Forces commands in codeblocks to show output +# MD033: No inline HTML +disable = [ + "MD014", + "MD033", +] + +[tool.rumdl.per-file-ignores] + +[tool.rumdl.MD013] # Line length +line_length = 999999 +reflow = true +reflow_mode = "normalize" + +[tool.rumdl.MD026] # Remove punctuation at the end of headings +punctuation = ",;:" + +[tool.rumdl.MD061] # Fail on certain strings. +#terms = ["TODO"] + [tool.setuptools_scm] # To enable SCM versioning, we need an empty tool configuration for setuptools_scm diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..ce5569f --- /dev/null +++ b/tox.ini @@ -0,0 +1,31 @@ +[tox] +envlist = pre-commit,towncrier-check,docs-lint,docs-all + +[testenv:pre-commit] +dependency_groups = pre-commit +commands = pre-commit run --all-files --show-diff-on-failure --color=always + +[testenv:towncrier{,-check}] +dependency_groups = towncrier +commands = + check : python -m towncrier.check --compare-with origin/main + !check : python -m towncrier {posargs} + +[docs] +docs_dir = {tox_root}{/}docs{/}en + +[testenv:docs{,-lint,-all,-live,-en}] +# Docs are always built on Python 3.12. See also the RTD config and contribution docs. +base_python = py312 +skip_install = true +setenv = + DISABLE_MKDOCS_2_WARNING = true + NO_MKDOCS_2_WARNING = 1 +dependency_groups = docs +commands = + !lint-!all-!live-!en : build_md_translations {posargs} en --source-code=stubs + lint : pyspelling + lint : markdown-checker --dir {[docs]docs_dir} --func check_broken_urls + live : live_serve_en {posargs} --port=8043 + all : build_md_translations {posargs} en --source-code=stubs + en : build_md_translations {posargs} en --source-code=stubs