├── .flake8 ├── .gitignore ├── .pre-commit-config.yaml ├── .prettierrc.toml ├── .readthedocs.yml ├── LICENSE ├── MANIFEST.in ├── README.md ├── docs ├── changelog.md ├── conf.py ├── design │ └── index.md ├── development │ └── index.md ├── expectations.md ├── glossary.md ├── goals.md ├── index.md ├── license.rst ├── requirements.txt └── usage │ ├── components │ ├── breadcrumbs.md │ ├── edit-this-page.md │ ├── ethical-ads.md │ ├── index.md │ ├── logo.md │ ├── related-pages.md │ ├── search-hide.md │ ├── search-input.md │ ├── sidebar-toggles.md │ └── view-this-page.md │ ├── getting-started.md │ └── skeleton.md ├── example ├── _static │ └── sample.css ├── _theme │ └── sections │ │ ├── announcement.html │ │ ├── article.html │ │ ├── footer-article.html │ │ ├── footer-content.html │ │ ├── footer.html │ │ ├── header-article.html │ │ ├── header-secondary.html │ │ ├── header.html │ │ ├── sidebar-primary.html │ │ └── sidebar-secondary.html ├── conf.py ├── index.md ├── requirements.txt ├── section-one │ ├── index.md │ ├── page-one-one.md │ └── page-one-two.md ├── section-two │ ├── index.md │ ├── page-two-one.md │ └── page-two-two.md ├── top-level-one.md ├── top-level-three.md └── top-level-two.md ├── noxfile.py ├── setup.cfg ├── setup.py ├── src └── sphinx_basic_ng │ ├── __init__.py │ └── theme │ └── basic-ng │ ├── changes │ ├── frameset.html │ ├── rstsource.html │ └── versionchanges.html │ ├── components │ ├── breadcrumbs.html │ ├── edit-this-page.html │ ├── ethical-ads.html │ ├── logo.html │ ├── related-pages.html │ ├── search-hide.html │ ├── search-input.html │ ├── toggle-sidebar-primary.html │ ├── toggle-sidebar-secondary.html │ └── view-this-page.html │ ├── defindex.html │ ├── domainindex.html │ ├── genindex-single.html │ ├── genindex-split.html │ ├── genindex.html │ ├── globaltoc.html │ ├── layout.html │ ├── localtoc.html │ ├── page.html │ ├── relations.html │ ├── search.html │ ├── searchbox.html │ ├── sections │ ├── announcement.html │ ├── article.html │ ├── footer-article.html │ ├── footer-content.html │ ├── footer.html │ ├── header-article.html │ ├── header-content.html │ ├── header-secondary.html │ ├── header.html │ ├── sidebar-primary.html │ └── sidebar-secondary.html │ ├── sourcelink.html │ ├── static │ ├── debug.css │ └── skeleton.css │ └── theme.conf └── tests └── barebones ├── conf.py ├── index.md ├── section-one ├── index.md ├── page-one-one.md └── page-one-two.md └── section-two ├── index.md ├── page-two-one.md └── page-two-two.md /.flake8: -------------------------------------------------------------------------------- 1 | [flake8] 2 | max-line-length = 88 3 | extend-ignore = E203,E501 4 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | wheels/ 23 | share/python-wheels/ 24 | *.egg-info/ 25 | .installed.cfg 26 | *.egg 27 | MANIFEST 28 | 29 | # PyInstaller 30 | # Usually these files are written by a python script from a template 31 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 32 | *.manifest 33 | *.spec 34 | 35 | # Installer logs 36 | pip-log.txt 37 | pip-delete-this-directory.txt 38 | 39 | # Unit test / coverage reports 40 | htmlcov/ 41 | .tox/ 42 | .nox/ 43 | .coverage 44 | .coverage.* 45 | .cache 46 | nosetests.xml 47 | coverage.xml 48 | *.cover 49 | *.py,cover 50 | .hypothesis/ 51 | .pytest_cache/ 52 | cover/ 53 | 54 | # Translations 55 | *.mo 56 | *.pot 57 | 58 | # Django stuff: 59 | *.log 60 | local_settings.py 61 | db.sqlite3 62 | db.sqlite3-journal 63 | 64 | # Flask stuff: 65 | instance/ 66 | .webassets-cache 67 | 68 | # Scrapy stuff: 69 | .scrapy 70 | 71 | # Sphinx documentation 72 | docs/_build/ 73 | 74 | # PyBuilder 75 | .pybuilder/ 76 | target/ 77 | 78 | # Jupyter Notebook 79 | .ipynb_checkpoints 80 | 81 | # IPython 82 | profile_default/ 83 | ipython_config.py 84 | 85 | # pyenv 86 | # For a library or package, you might want to ignore these files since the code is 87 | # intended to run in multiple environments; otherwise, check them in: 88 | # .python-version 89 | 90 | # pipenv 91 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. 92 | # However, in case of collaboration, if having platform-specific dependencies or dependencies 93 | # having no cross-platform support, pipenv may install dependencies that don't work, or not 94 | # install all needed dependencies. 95 | #Pipfile.lock 96 | 97 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow 98 | __pypackages__/ 99 | 100 | # Celery stuff 101 | celerybeat-schedule 102 | celerybeat.pid 103 | 104 | # SageMath parsed files 105 | *.sage.py 106 | 107 | # Environments 108 | .env 109 | .venv 110 | env/ 111 | venv/ 112 | ENV/ 113 | env.bak/ 114 | venv.bak/ 115 | 116 | # Spyder project settings 117 | .spyderproject 118 | .spyproject 119 | 120 | # Rope project settings 121 | .ropeproject 122 | 123 | # mkdocs documentation 124 | /site 125 | 126 | # mypy 127 | .mypy_cache/ 128 | .dmypy.json 129 | dmypy.json 130 | 131 | # Pyre type checker 132 | .pyre/ 133 | 134 | # pytype static type analyzer 135 | .pytype/ 136 | 137 | # Cython debug symbols 138 | cython_debug/ 139 | 140 | # Project specific 141 | tests/barebones/_templates 142 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | repos: 2 | - repo: https://github.com/psf/black 3 | rev: 20.8b1 4 | hooks: 5 | - id: black 6 | language_version: python3.8 7 | 8 | - repo: https://github.com/PyCQA/isort 9 | rev: 5.6.4 10 | hooks: 11 | - id: isort 12 | args: ["--profile", "black", "--filter-files"] 13 | 14 | - repo: https://gitlab.com/pycqa/flake8 15 | rev: 3.8.4 16 | hooks: 17 | - id: flake8 18 | 19 | - repo: https://github.com/pre-commit/mirrors-mypy 20 | rev: v0.812 21 | hooks: 22 | - id: mypy 23 | args: [--strict] 24 | files: src/.+\.py$ 25 | 26 | - repo: https://github.com/pre-commit/pre-commit-hooks 27 | rev: v3.2.0 28 | hooks: 29 | - id: check-builtin-literals 30 | - id: check-added-large-files 31 | - id: check-case-conflict 32 | - id: check-toml 33 | - id: check-yaml 34 | - id: debug-statements 35 | - id: end-of-file-fixer 36 | - id: forbid-new-submodules 37 | - id: trailing-whitespace 38 | 39 | - repo: https://github.com/PyCQA/pydocstyle 40 | rev: 5.1.1 41 | hooks: 42 | - id: pydocstyle 43 | files: src/.+\.py$ 44 | 45 | - repo: https://github.com/asottile/blacken-docs 46 | rev: v1.8.0 47 | hooks: 48 | - id: blacken-docs 49 | additional_dependencies: [black==20.8b1] 50 | 51 | - repo: https://github.com/pre-commit/mirrors-prettier 52 | rev: v2.1.2 53 | hooks: 54 | - id: prettier 55 | exclude: src/.+/theme/.+ 56 | 57 | - repo: https://github.com/mgedmin/check-manifest 58 | rev: "0.46" 59 | hooks: 60 | - id: check-manifest 61 | -------------------------------------------------------------------------------- /.prettierrc.toml: -------------------------------------------------------------------------------- 1 | useTabs = false 2 | proseWrap = "always" 3 | -------------------------------------------------------------------------------- /.readthedocs.yml: -------------------------------------------------------------------------------- 1 | # Read the Docs configuration file 2 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 3 | 4 | # Required 5 | version: 2 6 | sphinx: 7 | builder: dirhtml 8 | configuration: docs/conf.py 9 | 10 | python: 11 | version: 3.8 12 | install: 13 | - requirements: docs/requirements.txt 14 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2021 Pradyun Gedam 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy 4 | of this software and associated documentation files (the "Software"), to 5 | deal in the Software without restriction, including without limitation the 6 | rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 7 | sell copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in 11 | all copies or substantial portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 | FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE 16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 18 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 19 | IN THE SOFTWARE. 20 | -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | exclude .flake8 2 | exclude .pre-commit-config.yaml 3 | exclude noxfile.py 4 | 5 | include README.md 6 | include LICENSE 7 | 8 | recursive-include docs *.md 9 | recursive-include docs *.rst 10 | recursive-include docs *.png 11 | recursive-include docs *.py 12 | 13 | recursive-include src *.conf 14 | recursive-include src *.html 15 | recursive-include src *.css 16 | recursive-include src *.js 17 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # sphinx-basic-ng 2 | 3 | A modernised skeleton for Sphinx themes. 4 | 5 | ## To demo this theme 6 | 7 | 1. Clone this repository 8 | 9 | ```shell 10 | git clone https://github.com/pradyunsg/sphinx-basic-ng 11 | ``` 12 | 13 | 2. Install it locally 14 | 15 | ```shell 16 | pip install -e ./sphinx-basic-ng 17 | ``` 18 | 19 | 3. Install `nox` 20 | 21 | ```shell 22 | pip install nox 23 | ``` 24 | 25 | 4. Use `nox` to build a simple demo site 26 | 27 | ```shell 28 | nox -s docs-live -- ./tests/barebones 29 | ``` 30 | -------------------------------------------------------------------------------- /docs/changelog.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## 0.0.1.alpha12 4 | 5 | - Add a `view-this-page` component 6 | - Improve `edit-this-page` component's extensibility 7 | - Lint the entire codebase with prettier 8 | - Expand the documentation with more content 9 | - Tweak the size of the highest breakpoint 10 | 11 | ## 0.0.1.alpha11 12 | 13 | - Declare Sphinx 5 compatibility. 14 | - Drop support for Python 3.6. 15 | 16 | ## 0.0.1.alpha10 17 | 18 | - Move the container tag inside the container block. 19 | - Add a new `sections/header-content.html`. 20 | - Implement `search.html`. 21 | - Implement `genindex*.html`. 22 | - Implement `domainindex.html`. 23 | - Clarify handling of overlays for sidebars. 24 | - Improve handling of padding around main content. 25 | - Increase the z-index of overlay'd sidebars. 26 | 27 | ## 0.0.1.alpha9 28 | 29 | - Move the JS files to the end of body. 30 | 31 | ## 0.0.1.alpha8 32 | 33 | - Improve `debug.css`. 34 | - Expand the breadcrumbs conditional to do the right thing. 35 | - Include block names in endblock, in the Jinja templates. 36 | - Allow for full-width content styles. 37 | - Extend scaffold to fit 90rem screens. 38 | - Add `match-content-width` for content heading and footer. 39 | - Use viewport width for containers on mobile. 40 | - Only show `edit-this-page` if `source_suffix` is known. 41 | - Lightly tweak example theme. 42 | - Present better warnings in noxfile. 43 | - Drop `_html_page_context`. 44 | - Improve `breadcrumbs.html` implementation. 45 | - Add clearer "not implemented" warnings. 46 | - Drop the overflow handling, which is incompatible with `sticky`. 47 | 48 | ## 0.0.1.alpha7 49 | 50 | - Add additional breakpoint of 50rem (800px) for content width. 51 | 52 | ## 0.0.1.alpha6 53 | 54 | - Bump up to Sphinx 4. 55 | - Add example documentation, with an inline theme 56 | - Add header-article section. 57 | - Add `!important` for the hiding of sidebar toggles. 58 | - Fix the search input example. 59 | - Tweak announcement container, to not be centered. 60 | 61 | ## 0.0.1.alpha5 62 | 63 | - Allow omitting skeleton.css, via html-context. 64 | 65 | ## 0.0.1.alpha4 66 | 67 | - Add component: search-input 68 | - Add component: search-hide 69 | - Add components for toggling sidebars 70 | 71 | ## 0.0.1.alpha3 72 | 73 | - Add a nice introduction to `sections/article.html` 74 | - Add component: related-pages 75 | - Add responsive off-canvas sidebars, and corresponding components. 76 | - Host documentation on ReadTheDocs. 77 | - Rename certain sections of the scaffolding. 78 | - Add more headers and footers to the scaffolding. 79 | 80 | ## 0.0.1.alpha2 81 | 82 | - Add initial documentation scaffolding. 83 | - Add component: breadcrumbs 84 | - Add component: edit-this-page 85 | - Add component: ethical-ads 86 | - Add component: logo 87 | - Remove Sphinx variables from skeleton. 88 | - Updating terminology for parts of this project. 89 | 90 | ## 0.0.1.alpha1 91 | 92 | Initial release. 93 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # Full list of options can be found in the Sphinx documentation: 4 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 5 | 6 | # 7 | # -- Project information ----------------------------------------------------- 8 | # 9 | 10 | project = "sphinx-basic-ng" 11 | copyright = "2021, Pradyun Gedam" 12 | author = "Pradyun Gedam" 13 | 14 | # 15 | # -- General configuration --------------------------------------------------- 16 | # 17 | 18 | extensions = [ 19 | # Sphinx's own extensions 20 | "sphinx.ext.autodoc", 21 | "sphinx.ext.extlinks", 22 | "sphinx.ext.intersphinx", 23 | "sphinx.ext.mathjax", 24 | "sphinx.ext.todo", 25 | "sphinx.ext.viewcode", 26 | # External stuff 27 | "myst_parser", 28 | "sphinx_copybutton", 29 | "sphinx_inline_tabs", 30 | ] 31 | templates_path = ["_templates"] 32 | 33 | # 34 | # -- Options for extlinks ---------------------------------------------------- 35 | # 36 | extlinks = { 37 | "pypi": ("https://pypi.org/project/%s/", ""), 38 | } 39 | 40 | # 41 | # -- Options for intersphinx ------------------------------------------------- 42 | # 43 | intersphinx_mapping = { 44 | "python": ("https://docs.python.org/3", None), 45 | "sphinx": ("https://www.sphinx-doc.org/en/master", None), 46 | } 47 | 48 | # 49 | # -- Options for TODOs ------------------------------------------------------- 50 | # 51 | todo_include_todos = True 52 | 53 | # 54 | # -- Options for Markdown files ---------------------------------------------- 55 | # 56 | myst_enable_extensions = [ 57 | "deflist", 58 | ] 59 | myst_heading_anchors = 3 60 | 61 | # 62 | # -- Options for HTML output ------------------------------------------------- 63 | # 64 | 65 | html_theme = "furo" 66 | html_title = "sphinx-basic-ng" 67 | -------------------------------------------------------------------------------- /docs/design/index.md: -------------------------------------------------------------------------------- 1 | # Design 2 | 3 | This section describes how this theme is designed and how we're supposed to 4 | approach adding things to this theme. 5 | 6 | ```{toctree} 7 | :hidden: 8 | ``` 9 | 10 | ```{todo} 11 | Write this. 12 | ``` 13 | -------------------------------------------------------------------------------- /docs/development/index.md: -------------------------------------------------------------------------------- 1 | # Development 2 | 3 | This section contains information about how to do development work on this 4 | project. 5 | 6 | ```{toctree} 7 | :hidden: 8 | ``` 9 | 10 | ```{todo} 11 | Write this. 12 | ``` 13 | -------------------------------------------------------------------------------- /docs/expectations.md: -------------------------------------------------------------------------------- 1 | # Expectations 2 | 3 | This is an explanation page, describing what the expectations are around: 4 | 5 | - how this project is scoped, and why we might say no to certain things. 6 | - how this project will react to upstream Sphinx changes. 7 | - how this project would interact with derivative theme authors. 8 | 9 | ## Project Scope 10 | 11 | This project is intended to serve as a fairly-unopinionated base for Sphinx 12 | themes to use. It has one opinionated part -- the skeleton provided -- that can 13 | be removed/omitted if the theme authors wish to do so. 14 | 15 | Any new components added to the project should be generally applicable and 16 | should not need any Python code to support it. There is no reason to add 17 | theme-specific components, since derivative themes can extend the components 18 | they can use by adding a `components/.html` template file in their own 19 | source tree. 20 | 21 | ## Sphinx 22 | 23 | This project tracks the Sphinx project fairly loosely. The general expectation 24 | is that Sphinx will evolve slowly and there is no urgency in keeping up with a 25 | new Sphinx major version bump, when it happens. 26 | 27 | This project will be updated in response to changes in Sphinx, as quickly as 28 | feasible with the development and community management resources available. This 29 | does mean that, if this project does not have sufficient resources to do so, 30 | these updates will be slow. 31 | 32 | ## Derivative Themes 33 | 34 | At the time of writing, this project has a no backwards compatibility policy -- 35 | the project is in an alpha state, with only two known downstream themes: Furo 36 | and Lutra. 37 | 38 | If you do use this in your project, please feel welcome to do so! We'd 39 | appreciate if you reach out over the issue tracker to let us know that you're 40 | doing this. It's likely that there will be some changes to the skeleton as well 41 | as components, and we welcome any feedback on how to improve both of them and 42 | make them work better. 43 | -------------------------------------------------------------------------------- /docs/glossary.md: -------------------------------------------------------------------------------- 1 | # Glossary 2 | 3 | ```{glossary} 4 | Skeleton 5 | The markup provided in the `basic-ng` theme that implements a responsive 3-column layout. 6 | 7 | Sections 8 | Major areas of a page (e.g. sidebar, top bar, footer). 9 | 10 | Components 11 | Snippets of HTML that you put inside of sections, that use the template variables provided by Sphinx to compose common UI patterns for documentation websites (eg: breadcrumbs). 12 | ``` 13 | -------------------------------------------------------------------------------- /docs/goals.md: -------------------------------------------------------------------------------- 1 | # Goals 2 | 3 | The primary goal is to make it easier to write Sphinx themes, by providing theme 4 | authors with a consistent vocabulary for things in a Sphinx theme as well as an 5 | easy-to-build-upon base theme. The theme is meant to provide a nicer base theme 6 | for Sphinx theme authors than the Sphinx's built-in `basic` theme and to enable 7 | sharing of certain common components for documentation themes for Sphinx. 8 | 9 | ## What it provides 10 | 11 | Currently, `sphinx-basic-ng` provides two things to themes that derive from it: 12 | 13 | - Components for common design patterns on documentation websites. 14 | - Skeleton markup and styling for a 3-column website. 15 | 16 | Additionally, the documentation and implementation serves as a resource for all 17 | Sphinx theme authors on how to implement various common things in Sphinx themes 18 | (eg: breadcrumbs, edit this page buttons etc). 19 | 20 | ## What it does not provide 21 | 22 | This theme does not provide: 23 | 24 | - components that require any Python or Javascript to implement them. 25 | - styling for any of the components. 26 | - any styling beyond what is necessary for the skeleton markup. 27 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # sphinx-basic-ng 2 | 3 | A modern base for Sphinx themes, providing shared implementation of common 4 | components and a three-column layout to build upon. 5 | 6 | ```{toctree} 7 | :hidden: 8 | 9 | goals 10 | expectations 11 | ``` 12 | 13 | ```{toctree} 14 | :hidden: 15 | :caption: Usage 16 | 17 | usage/getting-started 18 | usage/skeleton 19 | usage/components/index 20 | glossary 21 | ``` 22 | 23 | ```{toctree} 24 | :hidden: 25 | :caption: Project 26 | 27 | development/index 28 | design/index 29 | changelog 30 | license 31 | GitHub 32 | ``` 33 | -------------------------------------------------------------------------------- /docs/license.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | License 3 | ======= 4 | 5 | **MIT License** 6 | 7 | .. include:: ../LICENSE 8 | -------------------------------------------------------------------------------- /docs/requirements.txt: -------------------------------------------------------------------------------- 1 | # This file primarily exists to allow ReadTheDocs to install this package 2 | # with the "docs" extra. The actual dependency information is held 3 | # in `pyproject.toml`. 4 | .[docs] 5 | -------------------------------------------------------------------------------- /docs/usage/components/breadcrumbs.md: -------------------------------------------------------------------------------- 1 | # Breadcrumbs 2 | 3 | A breadcrumb navigation provide links back to each "parent" page of the current 4 | page, showing the user's current location in a website and giving them a good 5 | way to navigate within it. 6 | 7 | ## Usage 8 | 9 | ```jinja 10 | {% include "components/breadcrumbs.html" %} 11 | ``` 12 | 13 | When there are no list-items to show in the breadcrumb, this component will 14 | render empty. 15 | 16 | In all other cases, the structure looks like: 17 | 18 | - a single `nav.breadcrumb-nav` 19 | - a single `ol.breadcrumb-nav-list` 20 | - one-or-more `breadcrumb-nav-list-item` containing a single `a[href]` tag. 21 | - a single `breadcrumb-nav-list-item` contain a single `span` tag. 22 | 23 | ```{tip} 24 | See [this page][w3schools-breadcrumbs] for an example of how to stylise 25 | breadcrumbs with this structure. 26 | ``` 27 | 28 | ## Configurability 29 | 30 | There are 2 values that can be provided via the html-context, which provide 31 | control over the components shown in the breadcrumbs: 32 | 33 | - `breadcrumb_include_index_as`: If provided, this name is used as the first 34 | list-item of the breadcrumb on pages other than the `index` page.The 35 | corresponding list-item will have an additional class: 36 | `breadcrumb-nav-index-item`. 37 | 38 | - `breadcrumb_include_page`: If truthy, the current page is included in the 39 | breadcrumb as the final list-item, with only a `span` (there's no `a[href]` in 40 | it). The corresponding list-item will have an additional class: 41 | `breadcrumb-nav-page-item`. 42 | 43 | [w3schools-breadcrumbs]: 44 | https://www.w3schools.com/howto/howto_css_breadcrumbs.asp 45 | -------------------------------------------------------------------------------- /docs/usage/components/edit-this-page.md: -------------------------------------------------------------------------------- 1 | # "Edit this page" link 2 | 3 | It is fairly common for technical documentation websites to contain a link to 4 | edit the original sources of a page. This makes it easy for a reader to quickly 5 | fix a typo and provides a decent way to navigate to the source repository of the 6 | project. 7 | 8 | ## Usage 9 | 10 | ```jinja 11 | {% include "components/edit-this-page.html" with context %} 12 | ``` 13 | 14 | This will add a single `a[href]` tag, with the text "Edit this page". 15 | 16 | You also need to declare the following in `theme.conf`'s `options` section: 17 | 18 | ```ini 19 | source_edit_link = 20 | source_repository = 21 | source_branch = 22 | source_directory = 23 | ``` 24 | 25 | ## Configurability 26 | 27 | The documentation author can set values in their `conf.py` file using 28 | `html_theme_options`: 29 | 30 | ```python 31 | html_theme_options = { 32 | "source_repository": "https://github.com/pradyunsg/sphinx-basic-ng/", 33 | "source_branch": "main", 34 | "source_directory": "docs/", 35 | } 36 | ``` 37 | 38 | ```python 39 | html_theme_options = { 40 | "source_edit_link": "https://my.host/project/edit/docs/{filename}", 41 | "source_repository": "https://my.host/project", 42 | "source_branch": "main", 43 | "source_directory": "docs/", 44 | } 45 | ``` 46 | 47 | Those user-provided values are used to determine the link for editing the 48 | generated page on their code hosting platform. 49 | 50 | This component can be customised in a theme-specific manner in two ways, both of 51 | which require adding a new template file (typically, 52 | `components/edit-this-page.html` file in the theme). 53 | 54 | 1. Extending 55 | 56 | This is be done by extending this file and overriding the the 57 | `link_available` and `link_not_available` blocks, which are used based on 58 | whether the edit link can be rendered -- i.e. whether the user has provided 59 | the configuration values noted above. 60 | 61 | ```jinja 62 | {% extends "basic-ng/components/edit-this-page.html" %} 63 | 64 | {% block link_not_available %} 65 | {{ warning("Hey user! Provide the repository information!" )}} 66 | {% endblock link_not_available %} 67 | ``` 68 | 69 | 2. Overriding 70 | 71 | This can be done by _not_ extending the base template. This allows the theme 72 | to have complete control over the way the URL provided is used. If a theme 73 | does this, it is also responsible for presenting warnings to the user when 74 | the user has not provided all the required configuration variables to the 75 | theme (see the sources of `edit-this-page.html`, after macros). 76 | 77 | It is possible to use the `determine_page_edit_link` macro, to get the 78 | relevant URL from the regular configuration (it assumes the user has it set). 79 | 80 | ```jinja 81 | {% from "basic-ng/components/edit-this-page.html" import determine_page_edit_link with context %} 82 | 83 | {{ _("Edit this page") }} 84 | ``` 85 | -------------------------------------------------------------------------------- /docs/usage/components/ethical-ads.md: -------------------------------------------------------------------------------- 1 | # Ethical Ads 2 | 3 | A lot of Sphinx documentation is hosted on [ReadTheDocs], who provide free docs 4 | hosting for open source projects. [Ethical Ads] is a privacy-respecting ad 5 | network built by ReadTheDocs, and is one of the contributors to their 6 | sustainability. 7 | 8 | Adding this component to your page in the correct places, helps you make sure 9 | that when ReadTheDocs tries to show ethical ads in documentation built with your 10 | theme, they are well integrated with it and show up where you expect them to be 11 | visible. 12 | 13 | ## Usage 14 | 15 | ```jinja 16 | {% include "components/ethical-ads.html" %} 17 | ``` 18 | 19 | This will add an empty `div` tag, which would be populated by ReadTheDocs. 20 | 21 | It is also expected that the page will [manually load ads]. This is done for 22 | pages hosted by ReadTheDocs automatically. 23 | 24 | ## Configurability 25 | 26 | There are 3 values that can be provided via the html-context, which correspond 27 | to the following configuration attributes on the ethical ad `div`: 28 | 29 | - `ethical_ad_class`: maps to `class` 30 | - `ethical_ad_type`: maps to `data-ea-type` 31 | - `ethical_ad_publisher`: maps to `data-ea-publisher` 32 | 33 | If these values are not set, they will take reasonable values for 34 | ReadTheDocs-based documentation. 35 | 36 | The `div` for the ad is only included on the page if the documentation is being 37 | built on ReadTheDocs or `ethical_ad_publisher` is set. 38 | 39 | ```{tip} 40 | If you need additional control/configuration, it is recommended to 41 | include the this component as shown here, and to override the 42 | `components/ethical-ads.html` file in your theme. 43 | ``` 44 | 45 | [readthedocs]: https://readthedocs.org/ 46 | [ethical ads]: https://www.ethicalads.io/ 47 | [manually load ads]: 48 | https://ethical-ad-client.readthedocs.io/en/latest/#manually-loading-ads 49 | -------------------------------------------------------------------------------- /docs/usage/components/index.md: -------------------------------------------------------------------------------- 1 | # Components 2 | 3 | The `basic-ng` theme provides various components. These serve as shared 4 | implementations of common needs and design patterns in documentation websites. 5 | 6 | ```{toctree} 7 | :maxdepth: 1 8 | 9 | breadcrumbs 10 | edit-this-page 11 | ethical-ads 12 | logo 13 | related-pages 14 | search-hide 15 | search-input 16 | sidebar-toggles 17 | view-this-page 18 | ``` 19 | -------------------------------------------------------------------------------- /docs/usage/components/logo.md: -------------------------------------------------------------------------------- 1 | # Site Logo 2 | 3 | Sphinx allows users to set a logo for their site, using the 4 | [`html_logo`][sphinx-html_logo] variable in `conf.py`. Themes are expected to 5 | have this on the page, if provided by the user. 6 | 7 | ## Usage 8 | 9 | ```jinja 10 | {% include "components/logo.html" %} 11 | ``` 12 | 13 | If the logo is set, this adds an `img.site-logo` with the correct URL for the 14 | logo. Otherwise, this is empty. 15 | 16 | ## Configurability 17 | 18 | None. 19 | -------------------------------------------------------------------------------- /docs/usage/components/related-pages.md: -------------------------------------------------------------------------------- 1 | # Related Pages 2 | 3 | Sphinx provides "next page" and "previous page" information, when rendering a 4 | page. This information is useful for documentation which has some sort of flow, 5 | as well as providing more navigational capabilities to the reader. 6 | 7 | ## Usage 8 | 9 | ```jinja 10 | {% include "components/related-pages.html" with context %} 11 | ``` 12 | 13 | This will add a single `div.related-pages`, which may be empty if the relevant 14 | information is not available in the html-context. 15 | 16 | The structure of this component is: 17 | 18 | - `div.related-pages` 19 | - `a[href].next-page` (omitted if there's no next page) 20 | - `div.page-info` 21 | - `div.context` 22 | - `span` 23 | - "Next" with translation 24 | - `div.title` 25 | - Title of the page 26 | - `a[href].prev-page` (omitted if there's no previous page) 27 | - `div.page-info` 28 | - `div.context` 29 | - `span` 30 | - "Previous" with translation 31 | - `div.title` 32 | - Title of the page 33 | 34 | ## Configurability 35 | 36 | None. 37 | 38 | Derivative themes may want to expose their own mechanism that allows hiding this 39 | component for documentation authors that don't want to provide this to the 40 | reader. 41 | -------------------------------------------------------------------------------- /docs/usage/components/search-hide.md: -------------------------------------------------------------------------------- 1 | # "Hide search matches" link 2 | 3 | Sphinx provides functionality to hide search matches, after the user lands on a 4 | page from search. This component exposes that to the user, allowing them to read 5 | the content once they've found it, without being distracted by the highlights. 6 | 7 | ## Usage 8 | 9 | ```jinja 10 | {% include "components/search-hide.html" %} 11 | {% include "components/toggle-sidebar-secondary.html" %} 12 | ``` 13 | 14 | This will add a single empty `div`, with the id `searchbox`. When a page has 15 | highlights, Sphinx's built-in search JS will inject the following HTML into this 16 | element: 17 | 18 | ```html 19 |

20 | Hide Search Matches 21 |

22 | ``` 23 | 24 | ## Configurability 25 | 26 | None. 27 | -------------------------------------------------------------------------------- /docs/usage/components/search-input.md: -------------------------------------------------------------------------------- 1 | # Search input 2 | 3 | Sphinx provides offline search to allow users to search the generated 4 | documentation. 5 | 6 | ## Usage 7 | 8 | ```jinja 9 | {% include "components/search-input.html" %} 10 | ``` 11 | 12 | This will add a single `form.search-container`, containing a single 13 | `input.search-input` with the translated placeholder text: "Search". Pressing 14 | {kbd}`Enter` in this element redirects the user to the search page, with the 15 | appropriate query parameters. 16 | 17 | ```{important} 18 | Sphinx's search JS looks inside elements with `[role="main"]`, so make sure that all user provided content is within an element with that attribute. 19 | ``` 20 | 21 | ## Configurability 22 | 23 | None. 24 | -------------------------------------------------------------------------------- /docs/usage/components/sidebar-toggles.md: -------------------------------------------------------------------------------- 1 | # Sidebar Drawer Toggles 2 | 3 | This is a component that is highly coupled with the skeleton provided. The 4 | skeleton uses sidebar drawers, as part of providing a responsive skeleton for 5 | the themes. As a part of this, the pages need to include toggles so that users 6 | can show/hide the corresponding sidebars. 7 | 8 | These components provide the user with the ability to include these drawers in 9 | an appropriate location on the page. 10 | 11 | ## Usage 12 | 13 | ```jinja 14 | {% include "components/toggle-sidebar-primary.html" %} 15 | {% include "components/toggle-sidebar-secondary.html" %} 16 | ``` 17 | 18 | This will add a single `label`, which contains a hamburger `svg` by default. 19 | These labels are hidden with `display: none` when the corresponding sidebar is 20 | visible-by-default. 21 | 22 | ## Configurability 23 | 24 | The theme author can change the inner contents of the label by overriding 25 | `{% block content %}`. 26 | -------------------------------------------------------------------------------- /docs/usage/components/view-this-page.md: -------------------------------------------------------------------------------- 1 | # "View this page" link 2 | 3 | It is fairly common for technical documentation websites to contain a link to 4 | view the original sources of a page. This makes it easy for a reader to quickly 5 | see how something is written in the markup and provides a decent way to navigate 6 | to the source repository of the project. 7 | 8 | ## Usage 9 | 10 | ```jinja 11 | {% include "components/view-this-page.html" with context %} 12 | ``` 13 | 14 | This will add a single `a[href]` tag, with the text "View this page". 15 | 16 | This uses the user-provided source repository links if provided. If they're not 17 | provided and the documentation is built with `html_copy_source = True` _and_ 18 | `html_show_sourcelink = True` (which are the default), the link points to the 19 | Sphinx-copied sources. 20 | 21 | You also need to declare the following in `theme.conf`'s `options` section: 22 | 23 | ```ini 24 | source_view_link = 25 | source_repository = 26 | source_branch = 27 | source_directory = 28 | ``` 29 | 30 | ## Configurability 31 | 32 | The documentation author can set values in their `conf.py` file using 33 | `html_theme_options`: 34 | 35 | ```python 36 | html_theme_options = { 37 | "source_repository": "https://github.com/pradyunsg/sphinx-basic-ng/", 38 | "source_branch": "main", 39 | "source_directory": "docs/", 40 | } 41 | ``` 42 | 43 | ```python 44 | html_theme_options = { 45 | "source_view_link": "https://my.host/project/view/docs/{filename}", 46 | "source_repository": "https://my.host/project", 47 | "source_branch": "main", 48 | "source_directory": "docs/", 49 | } 50 | ``` 51 | 52 | Those user-provided values are used to determine the link for viewing the 53 | generated page on the hosting platform. Currently supported platforms are 54 | `https://github.com`, `https://bitbucket.org` and `https://gitlab.io/`. 55 | 56 | This component can be customised in a theme-specific manner in two ways, both of 57 | which require adding a new template file (typically, 58 | `components/view-this-page.html` file in the theme). 59 | 60 | 1. Extending 61 | 62 | This is be done by extending this file and overriding the the 63 | `link_available` and `link_not_available` blocks, which are used based on 64 | whether the view link can be rendered -- i.e. whether the user has provided 65 | the configuration values noted above. 66 | 67 | ```jinja 68 | {% extends "basic-ng/components/view-this-page.html" %} 69 | 70 | {% block link_not_available %} 71 | {{ warning("Hey user! Provide the repository information!" )}} 72 | {% endblock link_not_available %} 73 | ``` 74 | 75 | 2. Overriding 76 | 77 | This can be done by _not_ extending the base template. This allows the theme 78 | to have complete control over the way the URL provided is used. If a theme 79 | does this, it is also responsible for presenting warnings to the user when 80 | the user has not provided all the required configuration variables to the 81 | theme (see the sources of `view-this-page.html`, after macros). 82 | 83 | It is possible to use the `determine_page_view_link` macro, to get the 84 | relevant URL from the regular configuration (it assumes the user has it set). 85 | 86 | ```jinja 87 | {% from "basic-ng/components/view-this-page.html" import determine_page_view_link with context %} 88 | 89 | {{ _("View this page") }} 90 | ``` 91 | -------------------------------------------------------------------------------- /docs/usage/getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | ```{todo} 4 | Write this as a tutorial. 5 | ``` 6 | -------------------------------------------------------------------------------- /docs/usage/skeleton.md: -------------------------------------------------------------------------------- 1 | # Skeleton 2 | 3 | ```{todo} 4 | Decide if this should be a single page or nested-bunch-of-pages. 5 | ``` 6 | 7 | ```{todo} 8 | Write this as reference sections, followed by how-to sections for 9 | various common things folks might want to do. 10 | ``` 11 | -------------------------------------------------------------------------------- /example/_static/sample.css: -------------------------------------------------------------------------------- 1 | /* 2 | This file doesn't really do much, and shouldn't be used as a basis of a theme. 3 | However, hopefully this does demonstrate that theme authors still need to 4 | write their own CSS for their theme. 5 | */ 6 | 7 | body { 8 | font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, 9 | "Apple Color Emoji", "Segoe UI Emoji"; 10 | } 11 | 12 | /* 13 | Announcement 14 | */ 15 | .site-announcement { 16 | background-color: #111; 17 | color: white; 18 | width: 100%; 19 | height: 3rem; 20 | display: flex; 21 | align-items: center; 22 | justify-content: center; 23 | } 24 | /* 25 | Header 26 | */ 27 | .sb-header label { 28 | display: flex; 29 | align-items: center; 30 | justify-content: center; 31 | height: 2rem; 32 | width: 2rem; 33 | } 34 | 35 | @media (max-width: 76rem) { 36 | .sb-header { 37 | border-bottom: 1px solid lightgray; 38 | height: 2rem; 39 | } 40 | .sb-header label[for="sb-sidebar-toggle--primary"] { 41 | float: left; 42 | } 43 | .sb-header label[for="sb-sidebar-toggle--secondary"] { 44 | float: right; 45 | } 46 | } 47 | 48 | /* 49 | Content 50 | */ 51 | h1 { 52 | margin-top: 1.5rem; 53 | font-size: 2rem; 54 | } 55 | h2 { 56 | font-size: 1.75rem; 57 | } 58 | h3 { 59 | font-size: 1.5rem; 60 | } 61 | h4 { 62 | font-size: 1.25rem; 63 | } 64 | h5 { 65 | font-size: 1.125rem; 66 | } 67 | h6 { 68 | text-transform: uppercase; 69 | } 70 | h1 .headerlink, 71 | h2 .headerlink, 72 | h3 .headerlink, 73 | h4 .headerlink, 74 | h5 .headerlink, 75 | h6 .headerlink { 76 | visibility: hidden; 77 | text-decoration: none; 78 | } 79 | h1:hover .headerlink, 80 | h2:hover .headerlink, 81 | h3:hover .headerlink, 82 | h4:hover .headerlink, 83 | h5:hover .headerlink, 84 | h6:hover .headerlink { 85 | visibility: visible; 86 | } 87 | 88 | /* Links */ 89 | a[href] { 90 | color: #0275d8; 91 | text-decoration: none; 92 | } 93 | a[href]:hover { 94 | color: #01447e; 95 | text-decoration: underline; 96 | } 97 | 98 | /* 99 | Sidebar (left) 100 | */ 101 | .sb-sidebar-primary { 102 | background: white; 103 | } 104 | /* Site name */ 105 | .site-name { 106 | margin: 1rem 2rem; 107 | font-size: 1.25rem; 108 | } 109 | .site-name a { 110 | color: inherit; 111 | } 112 | .site-name a:hover { 113 | text-decoration: none; 114 | } 115 | 116 | /* Search */ 117 | .search-container { 118 | margin: 1rem 2rem; 119 | } 120 | .search-input { 121 | box-sizing: border-box; 122 | width: 100%; 123 | padding: 0.5rem; 124 | 125 | font-size: 0.75rem; 126 | 127 | border: 0; 128 | border-radius: 0.25rem; 129 | 130 | background: #f8f9fa; 131 | color: black; 132 | } 133 | 134 | /* TOC tree */ 135 | .toctree-container { 136 | margin: 1rem 2rem; 137 | font-size: 0.875rem; 138 | } 139 | .toctree-container ul { 140 | list-style: none; 141 | padding-left: 1rem; 142 | margin: 0; 143 | } 144 | .toctree-container ul > li { 145 | padding: 0; 146 | padding-top: 0.5rem; 147 | } 148 | .toctree-container > ul { 149 | padding-left: 0; 150 | } 151 | .toctree-container > ul:first-child > li:first-child { 152 | padding-top: 0; 153 | } 154 | .toctree-container p.caption { 155 | margin-bottom: 0; 156 | } 157 | 158 | /* 159 | Sidebar (right) 160 | */ 161 | .sb-sidebar-secondary { 162 | background: white; 163 | } 164 | /* Table of contents */ 165 | .toc-container ul { 166 | font-size: 0.875rem; 167 | list-style: none; 168 | padding-left: 1rem; 169 | } 170 | .toc-container li { 171 | padding-top: 0.325rem; 172 | } 173 | 174 | /* 175 | Page footer 176 | */ 177 | .related-pages { 178 | height: 3rem; 179 | margin: 1rem 0; 180 | } 181 | .related-pages .context { 182 | font-size: 0.75rem; 183 | color: gray; 184 | } 185 | .related-pages a:hover { 186 | text-decoration: none; 187 | } 188 | .related-pages a:hover .title { 189 | text-decoration: underline; 190 | } 191 | .related-pages .next-page { 192 | height: 3rem; 193 | max-width: 50%; 194 | float: right; 195 | clear: right; 196 | text-align: right; 197 | } 198 | .related-pages .prev-page { 199 | height: 3rem; 200 | max-width: 50%; 201 | float: left; 202 | clear: left; 203 | text-align: left; 204 | } 205 | -------------------------------------------------------------------------------- /example/_theme/sections/announcement.html: -------------------------------------------------------------------------------- 1 | {% if theme_announcement is defined -%} 2 |
{{ theme_announcement }}
3 | {%- endif %} 4 | -------------------------------------------------------------------------------- /example/_theme/sections/article.html: -------------------------------------------------------------------------------- 1 | {{ body }} 2 | -------------------------------------------------------------------------------- /example/_theme/sections/footer-article.html: -------------------------------------------------------------------------------- 1 |
2 | {% if prev -%} 3 | 4 |
5 |
6 | {{ _("Previous") }} 7 |
8 | {% if prev.link == pathto(root_doc) %} 9 |
{{ _("Home") }}
10 | {% else %} 11 |
{{ prev.title }}
12 | {% endif %} 13 |
14 | 15 | {%- endif %} {% if next -%} 16 | 17 |
18 |
19 | {{ _("Next") }} 20 |
21 |
{{ next.title }}
22 |
23 | 24 | {%- endif %} 25 |
26 | -------------------------------------------------------------------------------- /example/_theme/sections/footer-content.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /example/_theme/sections/footer.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /example/_theme/sections/header-article.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /example/_theme/sections/header-secondary.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /example/_theme/sections/header.html: -------------------------------------------------------------------------------- 1 | {% include "components/toggle-sidebar-primary.html" %} {% include 2 | "components/toggle-sidebar-secondary.html" %} 3 | -------------------------------------------------------------------------------- /example/_theme/sections/sidebar-primary.html: -------------------------------------------------------------------------------- 1 |
2 | {{ docstitle }} 3 |
4 | {% include "components/search-input.html" %} 5 |
{{ toctree(titles_only=True) }}
6 | -------------------------------------------------------------------------------- /example/_theme/sections/sidebar-secondary.html: -------------------------------------------------------------------------------- 1 |
{{ toc }}
2 | -------------------------------------------------------------------------------- /example/conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # Full list of options can be found in the Sphinx documentation: 4 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 5 | 6 | # 7 | # -- Project information ----------------------------------------------------- 8 | # 9 | 10 | project = "sphinx-basic-ng sample" 11 | copyright = "2021, Pradyun Gedam" 12 | author = "Pradyun Gedam" 13 | 14 | # 15 | # -- General configuration --------------------------------------------------- 16 | # 17 | 18 | extensions = ["myst_parser"] 19 | 20 | # 21 | # -- Options for HTML output ------------------------------------------------- 22 | # 23 | 24 | html_theme = "basic-ng" 25 | html_style = "sample.css" 26 | templates_path = ["_theme"] 27 | html_static_path = ["_static"] 28 | html_context = { 29 | "theme_announcement": "Site wide announcement!", 30 | } 31 | -------------------------------------------------------------------------------- /example/index.md: -------------------------------------------------------------------------------- 1 | # Sample Documentation 2 | 3 | This is sample documentation, showing how `sphinx-basic-ng` can be used to 4 | simplify the development of a Sphinx theme. 5 | 6 | ```{toctree} 7 | top-level-one 8 | section-one/index 9 | Second Section 10 | top-level-two 11 | ``` 12 | 13 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 14 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 15 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 16 | voluptas? 17 | 18 | ```{toctree} 19 | :caption: Caption! 20 | :titlesonly: 21 | 22 | top-level-three 23 | external 24 | ``` 25 | -------------------------------------------------------------------------------- /example/requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx 2 | sphinx-autobuild 3 | myst_parser 4 | -------------------------------------------------------------------------------- /example/section-one/index.md: -------------------------------------------------------------------------------- 1 | # Section 1 2 | 3 | ```{toctree} 4 | page-one-one 5 | page-one-two 6 | ``` 7 | -------------------------------------------------------------------------------- /example/section-one/page-one-one.md: -------------------------------------------------------------------------------- 1 | # Page 1 in Section 1 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | -------------------------------------------------------------------------------- /example/section-one/page-one-two.md: -------------------------------------------------------------------------------- 1 | # Page 2 in Section 1 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | -------------------------------------------------------------------------------- /example/section-two/index.md: -------------------------------------------------------------------------------- 1 | # Section 2 2 | 3 | ```{toctree} 4 | page-two-one 5 | Alternative title 6 | ``` 7 | -------------------------------------------------------------------------------- /example/section-two/page-two-one.md: -------------------------------------------------------------------------------- 1 | # Page 1 in Section 2 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | -------------------------------------------------------------------------------- /example/section-two/page-two-two.md: -------------------------------------------------------------------------------- 1 | # Page 2 in Section 2 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | -------------------------------------------------------------------------------- /example/top-level-one.md: -------------------------------------------------------------------------------- 1 | # Page 1 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | 8 | ## Heading 1 9 | 10 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 11 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 12 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 13 | voluptas? 14 | 15 | ## Heading 2 16 | 17 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 18 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 19 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 20 | voluptas? 21 | -------------------------------------------------------------------------------- /example/top-level-three.md: -------------------------------------------------------------------------------- 1 | # Page 3 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | 8 | ## Heading 1 9 | 10 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 11 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 12 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 13 | voluptas? 14 | 15 | ## Heading 2 16 | 17 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 18 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 19 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 20 | voluptas? 21 | 22 | ## Heading 3 23 | 24 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 25 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 26 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 27 | voluptas? 28 | 29 | ## Heading 4 30 | 31 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 32 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 33 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 34 | voluptas? 35 | 36 | ## Heading 5 37 | 38 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 39 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 40 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 41 | voluptas? 42 | 43 | ## Heading 6 44 | 45 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 46 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 47 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 48 | voluptas? 49 | 50 | ## Heading 7 51 | 52 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 53 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 54 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 55 | voluptas? 56 | 57 | ## Heading 8 58 | 59 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 60 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 61 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 62 | voluptas? 63 | 64 | ## Heading 9 65 | 66 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 67 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 68 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 69 | voluptas? 70 | 71 | ## Heading 10 72 | 73 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 74 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 75 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 76 | voluptas? 77 | 78 | ## Heading 11 79 | 80 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 81 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 82 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 83 | voluptas? 84 | 85 | ## Heading 12 86 | 87 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 88 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 89 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 90 | voluptas? 91 | 92 | ## Heading 13 93 | 94 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 95 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 96 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 97 | voluptas? 98 | 99 | ## Heading 14 100 | 101 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 102 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 103 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 104 | voluptas? 105 | 106 | ## Heading 15 107 | 108 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 109 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 110 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 111 | voluptas? 112 | 113 | ## Heading 16 114 | 115 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 116 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 117 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 118 | voluptas? 119 | 120 | ## Heading 17 121 | 122 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 123 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 124 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 125 | voluptas? 126 | -------------------------------------------------------------------------------- /example/top-level-two.md: -------------------------------------------------------------------------------- 1 | # Page 2 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | 8 | ## Heading 1 9 | 10 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 11 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 12 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 13 | voluptas? 14 | 15 | ## Heading 2 16 | 17 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 18 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 19 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 20 | voluptas? 21 | -------------------------------------------------------------------------------- /noxfile.py: -------------------------------------------------------------------------------- 1 | """Development automation.""" 2 | 3 | import glob 4 | import os 5 | import shutil 6 | import tempfile 7 | 8 | import nox 9 | 10 | PACKAGE_NAME = "sphinx_basic_ng" 11 | nox.options.sessions = ["lint", "docs"] 12 | 13 | 14 | # 15 | # Development Sessions 16 | # 17 | @nox.session(name="docs-live", reuse_venv=True) 18 | def docs_live(session): 19 | if session.posargs: 20 | docs_dir, *additional_dependencies = session.posargs 21 | assert os.path.exists(docs_dir) and all( 22 | not arg[0] == "-" for arg in additional_dependencies 23 | ), "usage: [pip-install-arguments]..." 24 | else: 25 | docs_dir = "docs/" 26 | additional_dependencies = () 27 | 28 | session.install("-e", ".[docs]") 29 | session.install("sphinx-autobuild", *additional_dependencies) 30 | 31 | with tempfile.TemporaryDirectory() as destination: 32 | session.run( 33 | "sphinx-autobuild", 34 | # for sphinx-autobuild 35 | "--port=0", 36 | "--watch=src/", 37 | "--open-browser", 38 | # for sphinx 39 | "-b=dirhtml", 40 | "-a", 41 | "-v", 42 | docs_dir, 43 | destination, 44 | ) 45 | 46 | 47 | @nox.session(reuse_venv=True) 48 | def docs(session): 49 | session.install(".[docs]") 50 | 51 | # Generate documentation into `build/docs` 52 | session.run("sphinx-build", "-b", "dirhtml", "-v", "docs/", "build/docs") 53 | 54 | 55 | @nox.session(name="example-live", reuse_venv=True) 56 | def example_live(session): 57 | session.install("-e", ".") 58 | session.install("-r", "example/requirements.txt") 59 | 60 | with tempfile.TemporaryDirectory() as destination: 61 | session.run( 62 | "sphinx-autobuild", 63 | # for sphinx-autobuild 64 | "--port=0", 65 | "--watch=src/", 66 | "--open-browser", 67 | # for sphinx 68 | "-b=dirhtml", 69 | "-a", 70 | "example", 71 | destination, 72 | env={"PYTHONPATH": "example"}, 73 | ) 74 | 75 | 76 | @nox.session(reuse_venv=True) 77 | def example(session): 78 | session.install("-e", ".") 79 | session.install("-r", "example/requirements.txt") 80 | 81 | session.run( 82 | "sphinx-build", 83 | "-b=dirhtml", 84 | "-v", 85 | "example", 86 | "build/example-docs", 87 | env={"PYTHONPATH": "example"}, 88 | ) 89 | 90 | 91 | @nox.session(reuse_venv=True) 92 | def lint(session): 93 | session.install("pre-commit") 94 | 95 | args = list(session.posargs) 96 | args.append("--all-files") 97 | if "CI" in os.environ: 98 | args.append("--show-diff-on-failure") 99 | 100 | session.run("pre-commit", "run", *args) 101 | 102 | 103 | def get_release_versions(version_file): 104 | marker = "__version__ = " 105 | 106 | with open(version_file) as f: 107 | for line in f: 108 | if line.startswith(marker): 109 | version = line[len(marker) + 1 : -2] 110 | current_version, current_dev_number = version.split(".dev") 111 | break 112 | else: 113 | raise RuntimeError("Could not find current version.") 114 | 115 | next_dev_number = int(current_dev_number) + 1 116 | release_version = f"{current_version}.beta{next_dev_number}" 117 | next_version = f"{current_version}.dev{next_dev_number}" 118 | 119 | return release_version, next_version 120 | 121 | 122 | @nox.session 123 | def release(session): 124 | version_file = f"src/{PACKAGE_NAME}/__init__.py" 125 | allowed_upstreams = [ 126 | f"git@github.com:pradyunsg/{PACKAGE_NAME.replace('_', '-')}.git" 127 | ] 128 | 129 | release_version, next_version = get_release_versions(version_file) 130 | 131 | session.install("build", "twine", "release-helper") 132 | 133 | # Sanity Checks 134 | session.run("release-helper", "version-check-validity", release_version) 135 | session.run("release-helper", "version-check-validity", next_version) 136 | session.run("release-helper", "directory-check-empty", "dist") 137 | 138 | session.run("release-helper", "git-check-branch", "main") 139 | session.run("release-helper", "git-check-clean") 140 | session.run("release-helper", "git-check-tag", release_version, "--does-not-exist") 141 | session.run("release-helper", "git-check-remote", "origin", *allowed_upstreams) 142 | 143 | # Prepare release commit 144 | session.run("release-helper", "version-bump", version_file, release_version) 145 | session.run("git", "add", version_file, external=True) 146 | 147 | session.run( 148 | "git", "commit", "-m", f"Prepare release: {release_version}", external=True 149 | ) 150 | 151 | # Build the package 152 | if os.path.exists("build"): 153 | shutil.rmtree("build") 154 | session.run("python", "-m", "build") 155 | session.run("twine", "check", *glob.glob("dist/*")) 156 | 157 | # Tag the commit 158 | session.run( 159 | # fmt: off 160 | "git", "tag", release_version, "-m", f"Release {release_version}", "-s", 161 | external=True, 162 | # fmt: on 163 | ) 164 | 165 | # Prepare back-to-development commit 166 | session.run("release-helper", "version-bump", version_file, next_version) 167 | session.run("git", "add", version_file, external=True) 168 | session.run("git", "commit", "-m", "Back to development", external=True) 169 | 170 | # Push the commits and tag. 171 | session.run("git", "push", "origin", "main", release_version, external=True) 172 | 173 | # Upload the distributions. 174 | session.run("twine", "upload", *glob.glob("dist/*")) 175 | -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [metadata] 2 | name = sphinx_basic_ng 3 | version = attr:src.sphinx_basic_ng.__version__ 4 | 5 | author = Pradyun Gedam 6 | author_email = mail@pradyunsg.me 7 | 8 | description = A modern skeleton for Sphinx themes. 9 | long_description = file: README.md 10 | long_description_content_type = text/markdown 11 | 12 | url = https://github.com/pradyunsg/sphinx-basic-ng 13 | project_urls = 14 | Documentation = https://rtfd.io/sphinx-basic-ng/ 15 | 16 | classifiers = 17 | Framework :: Sphinx 18 | Framework :: Sphinx :: Theme 19 | License :: OSI Approved :: MIT License 20 | Environment :: Web Environment 21 | Intended Audience :: Developers 22 | Programming Language :: Python :: 3 23 | Operating System :: OS Independent 24 | Topic :: Documentation 25 | Topic :: Software Development :: Documentation 26 | 27 | [options] 28 | python_requires = >=3.7 29 | install_requires = 30 | sphinx >=4.0 31 | include_package_data = True 32 | packages=find: 33 | package_dir= 34 | =src 35 | 36 | [options.packages.find] 37 | where=src 38 | 39 | [options.extras_require] 40 | docs = 41 | furo 42 | myst-parser 43 | sphinx-copybutton 44 | sphinx-inline-tabs 45 | ipython 46 | 47 | [options.entry_points] 48 | sphinx.html_themes = 49 | basic-ng = sphinx_basic_ng 50 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | from setuptools import setup 2 | 3 | setup() 4 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/__init__.py: -------------------------------------------------------------------------------- 1 | """A modern skeleton for Sphinx themes.""" 2 | 3 | __version__ = "1.0.0.dev2" 4 | 5 | from pathlib import Path 6 | from typing import Any, Dict 7 | 8 | from sphinx.application import Sphinx 9 | 10 | _THEME_PATH = (Path(__file__).parent / "theme" / "basic-ng").resolve() 11 | 12 | 13 | def setup(app: Sphinx) -> Dict[str, Any]: 14 | """Entry point for sphinx theming.""" 15 | app.require_sphinx("4.0") 16 | 17 | app.add_html_theme("basic-ng", str(_THEME_PATH)) 18 | 19 | return { 20 | "parallel_read_safe": True, 21 | "parallel_write_safe": True, 22 | "version": __version__, 23 | } 24 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/changes/frameset.html: -------------------------------------------------------------------------------- 1 | {{ warning("This theme does not support changes/frameset.html") }} 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/changes/rstsource.html: -------------------------------------------------------------------------------- 1 | {{ warning("This theme does not support changes/rstsource.html") }} 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/changes/versionchanges.html: -------------------------------------------------------------------------------- 1 | {{ warning("This theme does not support changes/versionchanges.html") }} 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/components/breadcrumbs.html: -------------------------------------------------------------------------------- 1 | {% if (breadcrumb_include_index_as and pagename != 'index') or parents or breadcrumb_include_page -%} 2 | 15 | {%- endif -%} 16 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html: -------------------------------------------------------------------------------- 1 | {%- macro sanitise_trailing_slash(s) -%}{{ s.rstrip("/") }}{%- endmacro -%} 2 | 3 | {%- macro determine_page_edit_link() -%} 4 | {%- if theme_source_edit_link -%} 5 | {{ theme_source_edit_link.format(filename=pagename+page_source_suffix) }} 6 | {%- else -%} 7 | {#- First, sanitise the trailing slashes. -#} 8 | {%- set repo = sanitise_trailing_slash(theme_source_repository) -%} 9 | {%- set branch = theme_source_branch -%} 10 | {%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%} 11 | 12 | {#- Figure out the document's source file path. -#} 13 | {%- set relative_path = pagename + page_source_suffix -%} 14 | {%- if not subdirectory -%} 15 | {%- set document_path = relative_path -%} 16 | {%- else -%} 17 | {%- set document_path = subdirectory + "/" + relative_path -%} 18 | {%- endif -%} 19 | 20 | {#- Don't allow http:// URLs -#} 21 | {%- if repo.startswith( 22 | ( 23 | "http://github.com/", 24 | "http://gitlab.com/", 25 | "http://bitbucket.org/", 26 | ) 27 | ) -%} 28 | {{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }} 29 | {#- Handle the relevant cases -#} 30 | {%- elif repo.startswith("https://github.com/") -%} 31 | {{ repo }}/edit/{{ branch }}/{{ document_path }} 32 | {%- elif repo.startswith("https://gitlab.com/") -%} 33 | {{ repo }}/-/edit/{{ branch }}/{{ document_path }} 34 | {%- elif repo.startswith("https://bitbucket.org/") -%} 35 | {{ repo }}/src/{{ branch }}/{{ document_path }}?mode=edit&at={{ branch }} 36 | {#- Fail with a warning -#} 37 | {%- else -%} 38 | {{ warning( 39 | "Could not understand `source_repository` provided: " + repo + "\n" + 40 | "You should set `source_edit_link`, so that the edit link is presented." 41 | ) }} 42 | {%- endif -%} 43 | {%- endif -%} 44 | {%- endmacro -%} 45 | 46 | 47 | {%- if page_source_suffix -%} 48 | {%- set can_find_edit_link = ( 49 | (theme_source_edit_link and pagename) 50 | or (theme_source_repository and theme_source_branch) 51 | ) -%} 52 | {%- if can_find_edit_link -%} 53 | {%- block link_available -%} 54 | {{ _("Edit this page") }} 55 | {%- endblock link_available -%} 56 | {%- else -%} 57 | {%- block link_not_available -%}{%- endblock -%} 58 | {%- endif -%} 59 | {%- endif -%} 60 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/components/ethical-ads.html: -------------------------------------------------------------------------------- 1 | {% if READTHEDOCS or ethical_ad_publisher %} 2 |
9 | {% endif %} 10 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/components/logo.html: -------------------------------------------------------------------------------- 1 | {% if logo %} 2 | 3 | {% endif %} 4 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/components/related-pages.html: -------------------------------------------------------------------------------- 1 |
2 | {% if next -%} 3 | 4 |
5 |
6 | {{ _("Next") }} 7 |
8 |
{{ next.title }}
9 |
10 | 11 | 12 | {%- endif %} 13 | {% if prev -%} 14 | 15 | 16 |
17 |
18 | {{ _("Previous") }} 19 |
20 | {% if prev.link == pathto(master_doc) %} 21 |
{{ _("Home") }}
22 | {% else %} 23 |
{{ prev.title }}
24 | {% endif %} 25 |
26 | 27 | {%- endif %} 28 |
29 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/components/search-hide.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/components/search-input.html: -------------------------------------------------------------------------------- 1 |
2 | 3 |
4 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/components/toggle-sidebar-primary.html: -------------------------------------------------------------------------------- 1 | 21 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/components/toggle-sidebar-secondary.html: -------------------------------------------------------------------------------- 1 | 21 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html: -------------------------------------------------------------------------------- 1 | {%- macro sanitise_trailing_slash(s) -%}{{ s.rstrip("/") }}{%- endmacro -%} 2 | 3 | {%- macro determine_page_view_link() -%} 4 | {%- if theme_source_view_link -%} 5 | {{ theme_source_view_link.format(filename=pagename+page_source_suffix) }} 6 | {%- elif theme_source_repository -%} 7 | {#- First, sanitise the trailing slashes. -#} 8 | {%- set repo = sanitise_trailing_slash(theme_source_repository) -%} 9 | {%- set branch = theme_source_branch -%} 10 | {%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%} 11 | 12 | {#- Figure out the document's source file path. -#} 13 | {%- set relative_path = pagename + page_source_suffix -%} 14 | {%- if not subdirectory -%} 15 | {%- set document_path = relative_path -%} 16 | {%- else -%} 17 | {%- set document_path = subdirectory + "/" + relative_path -%} 18 | {%- endif -%} 19 | 20 | {#- Don't allow http:// URLs -#} 21 | {%- if repo.startswith( 22 | ( 23 | "http://github.com/", 24 | "http://gitlab.com/", 25 | "http://bitbucket.org/", 26 | ) 27 | ) -%} 28 | {{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }} 29 | {#- Handle the relevant cases -#} 30 | {%- elif repo.startswith("https://github.com/") -%} 31 | {{ repo }}/blob/{{ branch }}/{{ document_path }}?plain=1 32 | {%- elif repo.startswith("https://gitlab.com/") -%} 33 | {{ repo }}/blob/{{ branch }}/{{ document_path }} 34 | {%- elif repo.startswith("https://bitbucket.org/") -%} 35 | {{ repo }}/src/{{ branch }}/{{ document_path }} 36 | {#- Fail with a warning -#} 37 | {%- else -%} 38 | {{ warning( 39 | "Could not understand `source_repository` provided: " + repo + "\n" + 40 | "You should set `source_view_link`, so that the view link is presented." 41 | ) }} 42 | {%- endif -%} 43 | {%- elif show_source and has_source -%} 44 | {{ pathto('_sources/' + sourcename, true) }} 45 | {%- endif -%} 46 | {%- endmacro -%} 47 | 48 | 49 | {%- if page_source_suffix -%} 50 | {%- set can_find_view_link = ( 51 | (theme_source_view_link and pagename) 52 | or (show_source and has_source and sourcename) 53 | or (theme_source_repository and theme_source_branch) 54 | ) -%} 55 | {%- if can_find_view_link -%} 56 | {%- block link_available -%} 57 | {{ _("View sources") }} 58 | {%- endblock link_available -%} 59 | {%- else -%} 60 | {%- block link_not_available -%}{%- endblock -%} 61 | {%- endif -%} 62 | {%- endif -%} 63 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/defindex.html: -------------------------------------------------------------------------------- 1 | {{ warning('defindex.html template is not supported.') }} 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/domainindex.html: -------------------------------------------------------------------------------- 1 | {% extends "page.html" %} 2 | 3 | {% block head_title -%} 4 | {{ indextitle|striptags|e }} - {{ docstitle|striptags|e }} 5 | {% endblock head_title -%} 6 | 7 | {% block scripts -%} 8 | {{ super() }} 9 | {%- if not embedded and collapse_index %} 10 | 11 | {%- endif -%} 12 | {%- endblock scripts %} 13 | 14 | {% block content %} 15 |
16 |
17 | 18 | {% block content_inner %} 19 |
20 |

{{ indextitle }}

21 |
22 | {%- for (letter, entries) in content -%} 23 | {{ letter }} 24 | {%- if not loop.last %} | {% endif -%} 25 | {%- endfor -%} 26 |
27 |
28 | 29 | {%- set groupid = idgen() %} 30 | 31 | {%- for letter, entries in content %} 32 | 33 | 34 | 35 | 36 | 37 | 38 | {%- for (name, grouptype, page, anchor, extra, qualifier, description) in entries %} 39 | 40 | 44 | 51 | 52 | {%- endfor %} 53 | {%- endfor %} 54 |
 
{{ letter }}
{% if grouptype == 1 -%} 41 | 43 | {%- endif %}{% if grouptype == 2 %}   {% endif %} 45 | {% if page %}{% endif -%} 46 | {{ name|e }} 47 | {%- if page %}{% endif %} 48 | {%- if extra %} ({{ extra|e }}){% endif -%} 49 | {% if qualifier %}{{ qualifier|e }}:{% endif %} 50 | {{ description|e }}
55 | {% endblock content_inner %} 56 | 57 |
58 | {% endblock content %} 59 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/genindex-single.html: -------------------------------------------------------------------------------- 1 | {# Module: single page index, split by a "key" #} 2 | {% extends "page.html" %} 3 | 4 | {% block head_title -%} 5 | {{ _("Index") }} - {{ docstitle|striptags|e }} 6 | {%- endblock head_title %} 7 | 8 | {% macro indexentries(firstname, links) -%} 9 | {% if links -%} 10 | 11 | {%- if links[0][0] %}{% endif -%} 12 | {{ firstname|e }} 13 | {%- if links[0][0] %}{% endif -%} 14 | 15 | 16 | {%- for ismain, link in links[1:] -%} 17 | , 18 | {%- if ismain %}{% endif -%} 19 | [{{ loop.index }}] 20 | {%- if ismain %}{% endif -%} 21 | 22 | {%- endfor %} 23 | {%- else %} 24 | {{ firstname|e }} 25 | {%- endif %} 26 | {% endmacro %} 27 | 28 | {% block content %} 29 |
30 |
31 | 32 | {% block content_inner %} 33 |
34 |

{% trans key=key %}Index – {{ key }}{% endtrans %}

35 |
36 | 37 |
38 | 39 | {%- for column in entries|slice(2) if column %} 40 | 52 | {%- endfor %} 53 |
    41 | {%- for entryname, (links, subitems, _) in column %} 42 |
  • {{ indexentries(entryname, links) }} 43 | {%- if subitems %} 44 |
      45 | {%- for subentryname, subentrylinks in subitems %} 46 |
    • {{ indexentries(subentryname, subentrylinks) }}
      • 47 | {%- endfor %} 48 |
    49 | {%- endif -%}
    • 50 | {%- endfor %} 51 |
54 |
55 | {% endblock content_inner %} 56 | 57 |
58 | {% endblock %} 59 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/genindex-split.html: -------------------------------------------------------------------------------- 1 | {# Module: A single page of a multi-page index #} 2 | {% extends "page.html" %} 3 | 4 | {% block head_title -%} 5 | {{ _("Index") }} - {{ docstitle|striptags|e }} 6 | {%- endblock head_title %} 7 | 8 | {% block content %} 9 |
10 |
32 | {% endblock %} 33 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/genindex.html: -------------------------------------------------------------------------------- 1 | {% extends "page.html" %} 2 | 3 | {% block head_title -%} 4 | {{ _("Index") }} - {{ docstitle|striptags|e }} 5 | {%- endblock head_title %} 6 | 7 | {% macro indexentries(firstname, links) -%} 8 | {% if links -%} 9 | 10 | {%- if links[0][0] %}{% endif -%} 11 | {{ firstname|e }} 12 | {%- if links[0][0] %}{% endif -%} 13 | 14 | 15 | {%- for ismain, link in links[1:] -%} 16 | , 17 | {%- if ismain %}{% endif -%} 18 | [{{ loop.index }}] 19 | {%- if ismain %}{% endif -%} 20 | 21 | {%- endfor %} 22 | {%- else %} 23 | {{ firstname|e }} 24 | {%- endif %} 25 | {% endmacro %} 26 | 27 | {% block content %} 28 |
29 |
30 | 31 | {% block content_inner %} 32 |
33 |

{{ _('Index') }}

34 |
35 | {%- for key, dummy in genindexentries -%} 36 | {{ key }} 37 | {%- if not loop.last %} | {% endif -%} 38 | {%- endfor -%} 39 |
40 |
41 | 42 | {%- for key, entries in genindexentries %} 43 |
44 |

{{ key }}

45 | 46 | {%- for column in entries|slice_index(2) if column %} 47 | 59 | {%- endfor %} 60 |
    48 | {%- for entryname, (links, subitems, _) in column %} 49 |
  • {{ indexentries(entryname, links) }} 50 | {%- if subitems %} 51 |
      52 | {%- for subentryname, subentrylinks in subitems %} 53 |
    • {{ indexentries(subentryname, subentrylinks) }}
      • 54 | {%- endfor %} 55 |
    56 | {%- endif -%}
    • 57 | {%- endfor %} 58 |
61 |
62 | {% endfor %} 63 | {% endblock content_inner %} 64 | 65 |
66 | {% endblock %} 67 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/globaltoc.html: -------------------------------------------------------------------------------- 1 | {{ warning("This theme does not support globaltoc.html") }} 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/layout.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | {% block head_meta -%} 5 | 6 | 7 | 8 | {% if not skip_ua_compatible -%} 9 | 10 | {%- endif -%} 11 | 12 | {{ metatags }} 13 | 14 | {% endblock head_meta -%} 15 | 16 | {% block head_title %}{{ title|striptags|e }}{% endblock head_title %} 17 | 18 | {%- block head_links -%} 19 | 20 | {% if favicon -%} 21 | 22 | {%- endif -%} 23 | {% if hasdoc('about') -%} 24 | 25 | {%- endif -%} 26 | {% if hasdoc('genindex') -%} 27 | 28 | {%- endif -%} 29 | {% if hasdoc('search') -%} 30 | 31 | {%- endif -%} 32 | {% if hasdoc('copyright') -%} 33 | 34 | {%- endif -%} 35 | {% if next -%} 36 | 37 | {%- endif -%} 38 | {% if prev -%} 39 | 40 | {%- endif -%} 41 | 42 | {% endblock head_links -%} 43 | 44 | {% block head_stylesheets -%} 45 | {% if not omit_skeleton_css -%} 46 | 47 | {%- endif -%} 48 | 49 | {% for css in css_files -%} 50 | {%- if css|attr("filename") -%} 51 | {{ css_tag(css) }} 52 | {%- else -%} 53 | 54 | {%- endif -%} 55 | {% endfor -%} 56 | 57 | {%- endblock head_stylesheets -%} 58 | 59 | {% block head_javascript %}{% endblock %} 60 | {% block head_extra %}{% endblock %} 61 | 62 | 63 | {% block body %}{% endblock body -%} 64 | {% block body_javascript -%} 65 | {% for js in script_files -%} 66 | {{ js_tag(js) }} 67 | {% endfor -%} 68 | {%- endblock body_javascript -%} 69 | 70 | 71 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/localtoc.html: -------------------------------------------------------------------------------- 1 | {{ warning("This theme does not support localtoc.html") }} 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/page.html: -------------------------------------------------------------------------------- 1 | {# Layout: This is used by _every_ Sphinx content page #} 2 | {% extends "layout.html" %} 3 | 4 | {% block body %} 5 | {% block announcement %} 6 |
7 | {% include "sections/announcement.html" %} 8 |
9 | {% endblock announcement %} 10 | {% block header %} 11 |
12 |
13 | {% include "sections/header.html" %} 14 |
15 |
16 | {% endblock header %} 17 | {% block header_secondary %} 18 |
19 |
20 | {% include "sections/header-secondary.html" %} 21 |
22 |
23 | {% endblock header_secondary %} 24 | 25 | 26 | 27 | 28 | 29 | 30 | {% block container %} 31 |
32 |
33 | {% block sidebar_primary %} 34 | 37 | {% endblock sidebar_primary %} 38 |
39 | {% block header_content %} 40 |
41 |
42 | {% include "sections/header-content.html" %} 43 |
44 |
45 | {% endblock header_content %} 46 |
47 | {% block content %} 48 |
49 |
50 | {% include "sections/header-article.html" %} 51 |
52 |
53 | {% include "sections/article.html" %} 54 |
55 |
56 | {% include "sections/footer-article.html" %} 57 |
58 |
59 | {% endblock content %} 60 | {% block sidebar_secondary %} 61 | 64 | {% endblock sidebar_secondary %} 65 |
66 | {% block footer_content %} 67 |
68 |
69 | {% include "sections/footer-content.html" %} 70 |
71 |
72 | {% endblock footer_content %} 73 |
74 |
75 |
76 | {% endblock container %} 77 | {% block footer %} 78 |
79 |
80 | {% include "sections/footer.html" %} 81 |
82 |
83 | {% endblock footer %} 84 | {% endblock body %} 85 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/relations.html: -------------------------------------------------------------------------------- 1 | {{ warning("This theme does not support relations.html") }} 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/search.html: -------------------------------------------------------------------------------- 1 | {% extends "page.html" %} 2 | 3 | {% block head_title %}{{ _("Search") }} - {{ docstitle }}{% endblock head_title %} 4 | 5 | {% block content %} 6 |
7 |
8 | {% block before_results -%} 9 | 17 | {%- endblock %} 18 |
19 | {% block after_results %}{% endblock %} 20 |
21 |
22 | {% endblock content %} 23 | 24 | {% block body_javascript -%} 25 | {{ super() }} 26 | 27 | 28 | 29 | {%- endblock body_javascript %} 30 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/searchbox.html: -------------------------------------------------------------------------------- 1 | {{ warning("This theme does not support searchbox.html") }} 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/announcement.html: -------------------------------------------------------------------------------- 1 | sections/announcement.html 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/article.html: -------------------------------------------------------------------------------- 1 | sections/article.html 2 | 3 |

4 | Hi there! 5 |

6 |

7 | You seem to be trying to write a Sphinx theme! Nice! 8 |

9 |

10 | What you're seeing is the initial scaffolding provided by sphinx-basic-ng 11 | which should serve as a decent base for most 3-column layouts. 12 | If this is the first time you're seeing this, you probably want to be looking at the 13 | Getting Started 14 | page in the documentation. 15 |

16 |

17 | Every "section" of this page is populated using a template. The name of the template 18 | is visible in the sections. To override it, create your own template in the same 19 | path in your templates directory. For example, creating a template named 20 | sections/article.html will override this section. 21 |

22 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/footer-article.html: -------------------------------------------------------------------------------- 1 | sections/footer-article.html 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/footer-content.html: -------------------------------------------------------------------------------- 1 | sections/footer-content.html 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/footer.html: -------------------------------------------------------------------------------- 1 | sections/footer.html 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/header-article.html: -------------------------------------------------------------------------------- 1 | sections/header-article.html 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/header-content.html: -------------------------------------------------------------------------------- 1 | sections/header-content.html 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/header-secondary.html: -------------------------------------------------------------------------------- 1 | sections/header-secondary.html 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/header.html: -------------------------------------------------------------------------------- 1 | sections/header.html 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/sidebar-primary.html: -------------------------------------------------------------------------------- 1 | sections/sidebar-primary.html 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sections/sidebar-secondary.html: -------------------------------------------------------------------------------- 1 | sections/sidebar-secondary.html 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/sourcelink.html: -------------------------------------------------------------------------------- 1 | {{ warning("This theme does not support sourcelink.html") }} 2 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/static/debug.css: -------------------------------------------------------------------------------- 1 | /* 2 | This CSS file should be overridden by the theme authors. It's 3 | meant for debugging and developing the skeleton that this theme provides. 4 | */ 5 | body { 6 | font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, 7 | "Apple Color Emoji", "Segoe UI Emoji"; 8 | background: lavender; 9 | } 10 | .sb-announcement { 11 | background: rgb(131, 131, 131); 12 | } 13 | .sb-announcement__inner { 14 | background: black; 15 | color: white; 16 | } 17 | .sb-header { 18 | background: lightskyblue; 19 | } 20 | .sb-header__inner { 21 | background: royalblue; 22 | color: white; 23 | } 24 | .sb-header-secondary { 25 | background: lightcyan; 26 | } 27 | .sb-header-secondary__inner { 28 | background: cornflowerblue; 29 | color: white; 30 | } 31 | .sb-sidebar-primary { 32 | background: lightgreen; 33 | } 34 | .sb-main { 35 | background: blanchedalmond; 36 | } 37 | .sb-main__inner { 38 | background: antiquewhite; 39 | } 40 | .sb-header-article { 41 | background: lightsteelblue; 42 | } 43 | .sb-article-container { 44 | background: snow; 45 | } 46 | .sb-article-main { 47 | background: white; 48 | } 49 | .sb-footer-article { 50 | background: lightpink; 51 | } 52 | .sb-sidebar-secondary { 53 | background: lightgoldenrodyellow; 54 | } 55 | .sb-footer-content { 56 | background: plum; 57 | } 58 | .sb-footer-content__inner { 59 | background: palevioletred; 60 | } 61 | .sb-footer { 62 | background: pink; 63 | } 64 | .sb-footer__inner { 65 | background: salmon; 66 | } 67 | .sb-article { 68 | background: white; 69 | } 70 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/static/skeleton.css: -------------------------------------------------------------------------------- 1 | /* Some sane resets. */ 2 | html { 3 | height: 100%; 4 | } 5 | 6 | body { 7 | margin: 0; 8 | min-height: 100%; 9 | } 10 | 11 | /* All the flexbox magic! */ 12 | body, 13 | .sb-announcement, 14 | .sb-content, 15 | .sb-main, 16 | .sb-container, 17 | .sb-container__inner, 18 | .sb-article-container, 19 | .sb-footer-content, 20 | .sb-header, 21 | .sb-header-secondary, 22 | .sb-footer { 23 | display: flex; 24 | } 25 | 26 | /* These order things vertically */ 27 | body, 28 | .sb-main, 29 | .sb-article-container { 30 | flex-direction: column; 31 | } 32 | 33 | /* Put elements in the center */ 34 | .sb-header, 35 | .sb-header-secondary, 36 | .sb-container, 37 | .sb-content, 38 | .sb-footer, 39 | .sb-footer-content { 40 | justify-content: center; 41 | } 42 | /* Put elements at the ends */ 43 | .sb-article-container { 44 | justify-content: space-between; 45 | } 46 | 47 | /* These elements grow. */ 48 | .sb-main, 49 | .sb-content, 50 | .sb-container, 51 | article { 52 | flex-grow: 1; 53 | } 54 | 55 | /* Because padding making this wider is not fun */ 56 | article { 57 | box-sizing: border-box; 58 | } 59 | 60 | /* The announcements element should never be wider than the page. */ 61 | .sb-announcement { 62 | max-width: 100%; 63 | } 64 | 65 | .sb-sidebar-primary, 66 | .sb-sidebar-secondary { 67 | flex-shrink: 0; 68 | width: 17rem; 69 | } 70 | 71 | .sb-announcement__inner { 72 | justify-content: center; 73 | 74 | box-sizing: border-box; 75 | height: 3rem; 76 | 77 | overflow-x: auto; 78 | white-space: nowrap; 79 | } 80 | 81 | /* Sidebars, with checkbox-based toggle */ 82 | .sb-sidebar-primary, 83 | .sb-sidebar-secondary { 84 | position: fixed; 85 | height: 100%; 86 | top: 0; 87 | } 88 | 89 | .sb-sidebar-primary { 90 | left: -17rem; 91 | transition: left 250ms ease-in-out; 92 | } 93 | .sb-sidebar-secondary { 94 | right: -17rem; 95 | transition: right 250ms ease-in-out; 96 | } 97 | 98 | .sb-sidebar-toggle { 99 | display: none; 100 | } 101 | .sb-sidebar-overlay { 102 | position: fixed; 103 | top: 0; 104 | width: 0; 105 | height: 0; 106 | 107 | transition: width 0ms ease 250ms, height 0ms ease 250ms, opacity 250ms ease; 108 | 109 | opacity: 0; 110 | background-color: rgba(0, 0, 0, 0.54); 111 | } 112 | 113 | #sb-sidebar-toggle--primary:checked 114 | ~ .sb-sidebar-overlay[for="sb-sidebar-toggle--primary"], 115 | #sb-sidebar-toggle--secondary:checked 116 | ~ .sb-sidebar-overlay[for="sb-sidebar-toggle--secondary"] { 117 | width: 100%; 118 | height: 100%; 119 | opacity: 1; 120 | transition: width 0ms ease, height 0ms ease, opacity 250ms ease; 121 | } 122 | 123 | #sb-sidebar-toggle--primary:checked ~ .sb-container .sb-sidebar-primary { 124 | left: 0; 125 | } 126 | #sb-sidebar-toggle--secondary:checked ~ .sb-container .sb-sidebar-secondary { 127 | right: 0; 128 | } 129 | 130 | /* Full-width mode */ 131 | .drop-secondary-sidebar-for-full-width-content 132 | .hide-when-secondary-sidebar-shown { 133 | display: none !important; 134 | } 135 | .drop-secondary-sidebar-for-full-width-content .sb-sidebar-secondary { 136 | display: none !important; 137 | } 138 | 139 | /* Mobile views */ 140 | .sb-page-width { 141 | width: 100%; 142 | } 143 | 144 | .sb-article-container, 145 | .sb-footer-content__inner, 146 | .drop-secondary-sidebar-for-full-width-content .sb-article, 147 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 148 | width: 100vw; 149 | } 150 | 151 | .sb-article, 152 | .match-content-width { 153 | padding: 0 1rem; 154 | box-sizing: border-box; 155 | } 156 | 157 | @media (min-width: 32rem) { 158 | .sb-article, 159 | .match-content-width { 160 | padding: 0 2rem; 161 | } 162 | } 163 | 164 | /* Tablet views */ 165 | @media (min-width: 42rem) { 166 | .sb-article-container { 167 | width: auto; 168 | } 169 | .sb-footer-content__inner, 170 | .drop-secondary-sidebar-for-full-width-content .sb-article, 171 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 172 | width: 42rem; 173 | } 174 | .sb-article, 175 | .match-content-width { 176 | width: 42rem; 177 | } 178 | } 179 | @media (min-width: 46rem) { 180 | .sb-footer-content__inner, 181 | .drop-secondary-sidebar-for-full-width-content .sb-article, 182 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 183 | width: 46rem; 184 | } 185 | .sb-article, 186 | .match-content-width { 187 | width: 46rem; 188 | } 189 | } 190 | @media (min-width: 50rem) { 191 | .sb-footer-content__inner, 192 | .drop-secondary-sidebar-for-full-width-content .sb-article, 193 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 194 | width: 50rem; 195 | } 196 | .sb-article, 197 | .match-content-width { 198 | width: 50rem; 199 | } 200 | } 201 | 202 | /* Tablet views */ 203 | @media (min-width: 59rem) { 204 | .sb-sidebar-secondary { 205 | position: static; 206 | } 207 | .hide-when-secondary-sidebar-shown { 208 | display: none !important; 209 | } 210 | .sb-footer-content__inner, 211 | .drop-secondary-sidebar-for-full-width-content .sb-article, 212 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 213 | width: 59rem; 214 | } 215 | .sb-article, 216 | .match-content-width { 217 | width: 42rem; 218 | } 219 | } 220 | @media (min-width: 63rem) { 221 | .sb-footer-content__inner, 222 | .drop-secondary-sidebar-for-full-width-content .sb-article, 223 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 224 | width: 63rem; 225 | } 226 | .sb-article, 227 | .match-content-width { 228 | width: 46rem; 229 | } 230 | } 231 | @media (min-width: 67rem) { 232 | .sb-footer-content__inner, 233 | .drop-secondary-sidebar-for-full-width-content .sb-article, 234 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 235 | width: 67rem; 236 | } 237 | .sb-article, 238 | .match-content-width { 239 | width: 50rem; 240 | } 241 | } 242 | 243 | /* Desktop views */ 244 | @media (min-width: 76rem) { 245 | .sb-sidebar-primary { 246 | position: static; 247 | } 248 | .hide-when-primary-sidebar-shown { 249 | display: none !important; 250 | } 251 | .sb-footer-content__inner, 252 | .drop-secondary-sidebar-for-full-width-content .sb-article, 253 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 254 | width: 59rem; 255 | } 256 | .sb-article, 257 | .match-content-width { 258 | width: 42rem; 259 | } 260 | } 261 | 262 | /* Full desktop views */ 263 | @media (min-width: 80rem) { 264 | .sb-article, 265 | .match-content-width { 266 | width: 46rem; 267 | } 268 | .sb-footer-content__inner, 269 | .drop-secondary-sidebar-for-full-width-content .sb-article, 270 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 271 | width: 63rem; 272 | } 273 | } 274 | 275 | @media (min-width: 84rem) { 276 | .sb-article, 277 | .match-content-width { 278 | width: 50rem; 279 | } 280 | .sb-footer-content__inner, 281 | .drop-secondary-sidebar-for-full-width-content .sb-article, 282 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 283 | width: 67rem; 284 | } 285 | } 286 | 287 | @media (min-width: 88rem) { 288 | .sb-footer-content__inner, 289 | .drop-secondary-sidebar-for-full-width-content .sb-article, 290 | .drop-secondary-sidebar-for-full-width-content .match-content-width { 291 | width: 67rem; 292 | } 293 | .sb-page-width { 294 | width: 88rem; 295 | } 296 | } 297 | -------------------------------------------------------------------------------- /src/sphinx_basic_ng/theme/basic-ng/theme.conf: -------------------------------------------------------------------------------- 1 | [theme] 2 | inherit = basic 3 | stylesheet = debug.css 4 | sidebars = 5 | 6 | [options] 7 | -------------------------------------------------------------------------------- /tests/barebones/conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # Full list of options can be found in the Sphinx documentation: 4 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 5 | 6 | # 7 | # -- Project information ----------------------------------------------------- 8 | # 9 | 10 | project = "sphinx-basic-ng demo" 11 | copyright = "2021, Pradyun Gedam" 12 | author = "Pradyun Gedam" 13 | 14 | # 15 | # -- General configuration --------------------------------------------------- 16 | # 17 | 18 | extensions = ["myst_parser"] 19 | 20 | # 21 | # -- Options for HTML output ------------------------------------------------- 22 | # 23 | 24 | html_theme = "basic-ng" 25 | templates_path = ["_templates"] 26 | -------------------------------------------------------------------------------- /tests/barebones/index.md: -------------------------------------------------------------------------------- 1 | # sphinx-basic-ng 2 | 3 | A modern skeleton for Sphinx themes. 4 | 5 | The template for each section is displayed on this page. To override it, create 6 | your own template in the same location. For example, 7 | `sections/article-main.html` will override the announcement HTML. 8 | 9 | Below is a sample Table of Contents. 10 | 11 | ```{toctree} 12 | :glob: 13 | 14 | section-one/index 15 | ``` 16 | 17 | ```{toctree} 18 | :glob: 19 | :caption: Caption 20 | 21 | section-two/index 22 | ``` 23 | -------------------------------------------------------------------------------- /tests/barebones/section-one/index.md: -------------------------------------------------------------------------------- 1 | # Section 1 2 | 3 | ```{toctree} 4 | page-one-one 5 | page-one-two 6 | ``` 7 | -------------------------------------------------------------------------------- /tests/barebones/section-one/page-one-one.md: -------------------------------------------------------------------------------- 1 | # Page 1 in Section 1 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | -------------------------------------------------------------------------------- /tests/barebones/section-one/page-one-two.md: -------------------------------------------------------------------------------- 1 | # Page 2 in Section 1 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | -------------------------------------------------------------------------------- /tests/barebones/section-two/index.md: -------------------------------------------------------------------------------- 1 | # Section 2 2 | 3 | ```{toctree} 4 | page-two-one 5 | page-two-two 6 | ``` 7 | -------------------------------------------------------------------------------- /tests/barebones/section-two/page-two-one.md: -------------------------------------------------------------------------------- 1 | # Page 1 in Section 2 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | -------------------------------------------------------------------------------- /tests/barebones/section-two/page-two-two.md: -------------------------------------------------------------------------------- 1 | # Page 2 in Section 2 2 | 3 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Soluta quod nulla 4 | officia! Ratione voluptate distinctio in architecto! Reprehenderit neque dicta 5 | in eligendi similique obcaecati eos? Quibusdam assumenda pariatur dolore 6 | voluptas? 7 | --------------------------------------------------------------------------------