Merge pull request #16 from devanshshukla99/update-docs

Update docs
devanshshukla99 · May 3, 2023 · 897cb33 · 897cb33
2 parents eee69ce + 2823a29
commit 897cb33
Show file tree

Hide file tree

Showing 19 changed files with 110 additions and 69 deletions.
diff --git a/README.rst b/README.rst
@@ -2,9 +2,12 @@
 sphinx-versioned-docs
 =====================
 
-|build| |docs| |codestyle|
+|build| |CI themes| |docs| |codestyle|
 
 Sphinx extension that allows building versioned docs for self-hosting.
+Supported on Linux and macOS.
+
+It works by producing docs for all(specified) branches in separate folders and injects a readthedocs-like version selector menu/badge.
 
 This project is a fork of `Smile-SA/sphinx-versions <https://github.com/Smile-SA/sphinx-versions>`_ with significant changes.
 
@@ -13,13 +16,27 @@ Get started using the `documentation`_
 How to use
 ==========
 
-Most basic usage:
-
 .. code:: bash
 
  sphinx-versioned --help
  sphinx-versioned build --help
 
+.. code::
+
+ Usage: sphinx-versioned build [OPTIONS]
+
+ ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+ │ --chdir TEXT Make this the current working directory before running. [default: None] │
+ │ --output -O TEXT Output directory [default: docs/_build] │
+ │ --git-root TEXT Path to directory in the local repo. Default is CWD. │
+ │ --local-conf TEXT Path to conf.py for sphinx-versions to read config from. [default: docs/conf.py] │
+ │ --root-ref -r TEXT The branch/tag at the root of DESTINATION. Will also be in subdir. [default: main] │
+ │ --prebuild --no-prebuild Disables the pre-builds; halves the runtime [default: prebuild] │
+ │ --branches -b TEXT Build docs for specific branches and tags [default: None] │
+ │ --quite --no-quite No output from `sphinx` [default: quite] │
+ │ --help Show this message and exit. │
+ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+
 .. |build| image:: https://github.com/devanshshukla99/sphinx-versioned-docs/actions/workflows/main.yml/badge.svg
  :alt: CI
 
@@ -29,5 +46,8 @@ Most basic usage:
 .. |docs| image:: https://readthedocs.org/projects/sphinx-versioned-docs/badge/?version=latest
  :target: https://sphinx-versioned-docs.readthedocs.io/en/latest/?badge=latest
  :alt: Documentation Status
+
+.. |CI themes| image:: https://github.com/devanshshukla99/sphinx-versioned-docs/actions/workflows/CI-themes.yml/badge.svg
+ :alt: CI themes
 
 .. _documentation: https://sphinx-versioned-docs.readthedocs.io/en/latest/
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,43 @@
+===================
+⚙API documentation
+===================
+
+main
+----
+
+.. automodule:: sphinx_versioned.__main__
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+----------
+
+sphinx extension
+----------------
+
+.. automodule:: sphinx_versioned.sphinx_
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+----------
+
+Versions container
+------------------
+
+.. automodule:: sphinx_versioned.versions
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+----------
+
+Util
+----
+
+.. automodule:: sphinx_versioned.lib
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+----------
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -15,8 +15,8 @@ In order to contribute to this project you'll need to install the package via so
 
  python -m pip install -e .[all]
 
-Build and upload a new version of sphinx-versions
-=================================================
+Build and upload a new version of sphinx-versioned-docs
+=======================================================
 
 Update the README.rst
 ---------------------
@@ -40,4 +40,4 @@ Upload your package to nexus
 
  twine upload dist/*
 
-After this command, your package is available on https://pypi.org. Anyone can install it using `pip install sphinx-versions`.
+After this command, your package is available on https://pypi.org. Anyone can install it using `pip install sphinx-versioned-docs`.
diff --git a/docs/index.rst b/docs/index.rst
@@ -5,10 +5,11 @@ sphinx-versioned-docs
 A Sphinx extension that lets you build Sphinx docs for all versions of your project without needing special hosting
 services.
 
+.. include:: ../README.rst
+
 Project Links
 =============
 
-* Documentation: https://sphinx-versioned-docs.readthedocs.io/en/latest/
 * Source code: https://github.com/devanshshukla99/sphinx-versioned-docs
 
 .. toctree::
@@ -18,6 +19,7 @@ Project Links
  install
  tutorial
  themes
+ api
 
 .. toctree::
  :maxdepth: 1

diff --git a/docs/install.rst b/docs/install.rst
@@ -9,6 +9,13 @@ Installation
 Requirements
 ============
 
+- GitPython>=3.1.31
+- loguru>=0.7.0
+- setuptools>=66.0.0
+- sphinx>=4.6.0
+- typer>=0.9.0
+- rich
+
 Installing from source
 ----------------------
 
@@ -19,7 +26,7 @@ Installing from source
  $ pip install .
 
 
-Installing from PyPi
+Installing using pip
 --------------------
 
 .. code-block:: bash

diff --git a/docs/screenshots/alabaster.png b/docs/screenshots/alabaster.png
diff --git a/docs/screenshots/bizstyle.png b/docs/screenshots/bizstyle.png
diff --git a/docs/screenshots/classic.png b/docs/screenshots/classic.png
diff --git a/docs/screenshots/nature.png b/docs/screenshots/nature.png
diff --git a/docs/screenshots/pyramid.png b/docs/screenshots/pyramid.png
diff --git a/docs/screenshots/sphinx_rtd_theme.png b/docs/screenshots/sphinx_rtd_theme.png
diff --git a/docs/screenshots/sphinx_rtd_theme_banner_dev.png b/docs/screenshots/sphinx_rtd_theme_banner_dev.png
diff --git a/docs/screenshots/sphinx_rtd_theme_banner_nourl.png b/docs/screenshots/sphinx_rtd_theme_banner_nourl.png
diff --git a/docs/screenshots/sphinx_rtd_theme_banner_old.png b/docs/screenshots/sphinx_rtd_theme_banner_old.png
diff --git a/docs/screenshots/sphinxdoc.png b/docs/screenshots/sphinxdoc.png
diff --git a/docs/screenshots/traditional.png b/docs/screenshots/traditional.png
diff --git a/docs/themes.rst b/docs/themes.rst
@@ -1,44 +1,20 @@
 .. _themes:
 
 ================
-Supported Themes
+Supported themes
 ================
 
-Below are screen shots of the supported built-in Sphinx themes. You can the "Versions" section in each screen shot on
-sidebars.
+This project supports multiple themes such as:
 
-sphinx_rtd_theme
-----------------
+|CI themes|
 
-.. figure:: screenshots/sphinx_rtd_theme.png
- :target: _images/sphinx_rtd_theme.png
+- sphinx_rtd_theme
+- astropy_sphinx_theme
+- alabaster
+- sphinxdoc
+- pyramid
+- bizstyle
+- traditional
 
-alabaster
----------
-
-.. figure:: screenshots/alabaster.png
- :target: _images/alabaster.png
-
-sphinxdoc
----------
-
-.. figure:: screenshots/sphinxdoc.png
- :target: _images/sphinxdoc.png
-
-bizstyle
---------
-
-.. figure:: screenshots/bizstyle.png
- :target: _images/bizstyle.png
-
-pyramid
--------
-
-.. figure:: screenshots/pyramid.png
- :target: _images/pyramid.png
-
-traditional
------------
-
-.. figure:: screenshots/traditional.png
- :target: _images/traditional.png
+.. |CI themes| image:: https://github.com/devanshshukla99/sphinx-versioned-docs/actions/workflows/CI-themes.yml/badge.svg
+ :alt: CI themes
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
@@ -9,53 +9,45 @@ This guide will go over the basics of the project.
 Make sure that you've already :ref:`installed <install>` it.
 
 
-Building Docs Locally
+Building docs locally
 =====================
 
 Before we begin make sure you have some Sphinx docs already in your project. If not, read `First Steps with Sphinx <http://www.sphinx-doc.org/en/stable/tutorial.html>`_ first. If you just want something quick
 and dirty you can do the following:
 
 .. code-block:: bash
 
- git checkout -b feature_branch master # Create new branch from master.
+ git checkout -b feature_branch main # Create new branch from main.
  mkdir docs # All documentation will go here (optional, can be anywhere).
  echo "master_doc = 'index'" > docs/conf.py # Create Sphinx config file.
  echo -e "Test\n====\n\nSample Documentation" > docs/index.rst # Create one doc.
  git add docs
  git commit
- git push origin feature_branch # Required.
 
-.. note::
 
- It is **required** to push doc files to origin. ``sphinx-versioned-docs`` only works with remote branches/tags and ignores any
- local changes (committed, staged, unstaged, etc). If you don't push to origin ``sphinx-versioned-docs`` won't see them. This
- eliminates race conditions when multiple CI jobs are building docs at the same time.
+Building versioned docs
+=======================
+
+By default, ``sphinx-versioned-docs`` will try to build all tags and branches present in the git repo, using the command:
 
-.. _build-all-versions:
+.. code-block:: bash
 
-Build All Versions
-==================
+ sphinx-versioned build
 
-Now that you've got docs pushed to origin and they build fine with ``sphinx-build`` let's try building them with
-sphinx-versions:
+However, to build some particular branch(s) and tag(s), they can be specified in the ``--branches`` argument as:
 
 .. code-block:: bash
 
- sphinx-versioned build -r feature_branch docs docs/_build/html
- open docs/_build/html/index.html
+ sphinx-versioned build --branches "main, docs"
 
-.. More information about all of the options can be found at :ref:`settings` or by running with ``--help`` but just for
-.. convenience:
+This command will build the ``main`` and ``docs`` branches.
 
-.. * ``-r feature_branch`` tells the program to build our newly created/pushed branch at the root of the "html" directory.
-.. We do this assuming there are no docs in master yet. Otherwise you can omit this argument.
-.. * ``docs/_build/html`` is the destination directory that holds generated HTML files.
-.. * The final ``docs`` argument is the directory where we put our RST files in, relative to the git root (e.g. if you
-.. clone your repo to another directory, that would be the git root directory). You can add more relative paths if you've
-.. moved the location of your RST files between different branches/tags.
+After the build has succeded, your docs should be available in `docs/_build/<branch>/index.html` with a "Versions" section in the sidebar.
 
-.. The command should have worked and your docs should be available in `docs/_build/html/index.html` with a "Versions"
-.. section in the sidebar.
+.. note::
+
+ To get output from the sphinx builder, ``--no-quite`` option is required.
 
-.. .. note:: You can add a `-P pdf-file-name.pdf` option to also generate a pdf of all versions of your documentation
+.. note::
 
+ By default, ``sphinx-versioned-docs`` pre-builds the branches to see which of them fails; but this behaviour can be mitigated using the ``--no-prebuild`` argument.
diff --git a/setup.cfg b/setup.cfg
@@ -34,6 +34,7 @@ install_requires =
  setuptools>=66.0.0
  sphinx>=4.6.0
  typer>=0.9.0
+ rich
 
 
 [options.packages.find]