├── .gitignore ├── CHANGES.rst ├── MANIFEST.in ├── README.rst ├── docs ├── Makefile ├── _static │ └── example.gif ├── conf.py └── index.rst ├── lexer ├── examplefiles │ └── example.osexample ├── test-osexample.py └── test.sh ├── requirements.txt ├── setup.cfg ├── setup.py ├── sphinxcontrib ├── __init__.py ├── osexample.css ├── osexample.js └── osexample.py └── tox.ini /.gitignore: -------------------------------------------------------------------------------- 1 | *egg-info 2 | *.pyc 3 | .idea 4 | .installed.cfg 5 | .DS_Store 6 | docs/_build/* 7 | include/ 8 | lib/ 9 | lib64 10 | pip-selfcheck.json 11 | 12 | -------------------------------------------------------------------------------- /CHANGES.rst: -------------------------------------------------------------------------------- 1 | Changelog 2 | ========= 3 | 4 | 0.1.2 (unreleased) 5 | ------------------ 6 | 7 | - Nothing changed yet. 8 | 9 | 10 | 0.1.1 (2016-01-15) 11 | ------------------ 12 | 13 | - add basic homebrew lexer [svx] 14 | - add basic osx pkg lexer [svx] 15 | - include README into setup.py [svx] 16 | 17 | 18 | 0.1.0 (2015-12-26) 19 | ------------------ 20 | 21 | - initial fork [svx] 22 | -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | # includes 2 | include README.* 3 | include LICENSE 4 | include CHANGES.* 5 | recursive-include sphinxcontrib *.css *.js 6 | 7 | # excludes 8 | prune docs 9 | prune lexer 10 | exclude tox.ini 11 | exclude requirements.txt 12 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | .. -*- restructuredtext -*- 2 | 3 | .. image:: https://readthedocs.org/projects/sphinxcontrib-osexample/badge/?version=stable 4 | :target: http://sphinxcontrib-osexample.readthedocs.org/en/latest/?badge=stable 5 | :alt: Documentation Status 6 | 7 | 8 | ============================== 9 | osexample extension for Sphinx 10 | ============================== 11 | 12 | This is a modified fork of Serge Domkowski's `examplecode extension `_ for Sphinx. 13 | 14 | About 15 | ===== 16 | 17 | This is a simple extension that, when rendered as HTML, will fold multiple 18 | code blocks containing different operating systems administration examples into a single block 19 | which can be toggled from one to another using buttons. 20 | 21 | It's intended to be used for displaying package manager examples. 22 | (e.g., apt install or dnf install). 23 | 24 | This extension adds the ``example-code`` directive which adds a class to 25 | a container wrapping the code blocks that should be folded. The class allows 26 | the included Javascript and CSS to render the folded block and buttons. 27 | 28 | Currently supported are: Debian, Ubuntu, Fedora, CentOS, OSX 29 | 30 | Quick Example 31 | ------------- 32 | 33 | Source would look something like this:: 34 | 35 | .. example-code:: 36 | .. code-block:: Debian 37 | 38 | sudo apt install htop 39 | 40 | .. code-block:: Fedora 41 | 42 | sudo dnf install htop 43 | 44 | 45 | This will create an output like this: 46 | 47 | .. image:: https://raw.githubusercontent.com/svx/sphinxcontrib-osexample/master/docs/_static/example.gif 48 | :alt: Example how it looks like as generated HTML 49 | 50 | 51 | Installation 52 | ------------ 53 | 54 | .. code-block:: bash 55 | 56 | $ pip install sphinxcontrib-osexample 57 | 58 | 59 | Enabling the extension in Sphinx 60 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 61 | 62 | Just add sphinxcontrib.examplecode to the list of extensions in the conf.py file. For example: 63 | 64 | .. code-block:: bash 65 | 66 | extensions = ['sphinxcontrib.osexample'] 67 | 68 | 69 | 70 | Documentation 71 | ------------- 72 | 73 | Full documentation for end users can be found in the "docs" folder. 74 | 75 | It is also available online on `Read The Docs `_ 76 | 77 | Contribute 78 | ---------- 79 | 80 | - `Issue Tracker `_ 81 | - `Source Code `_ 82 | 83 | Support 84 | ------- 85 | 86 | If you are having issues, please let us know. 87 | 88 | 89 | License 90 | ------- 91 | 92 | The project is licensed under BSD. 93 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = _build 9 | 10 | # User-friendly check for sphinx-build 11 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) 12 | $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) 13 | endif 14 | 15 | # Internal variables. 16 | PAPEROPT_a4 = -D latex_paper_size=a4 17 | PAPEROPT_letter = -D latex_paper_size=letter 18 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 19 | # the i18n builder cannot share the environment and doctrees with the others 20 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 21 | 22 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext 23 | 24 | help: 25 | @echo "Please use \`make ' where is one of" 26 | @echo " html to make standalone HTML files" 27 | @echo " dirhtml to make HTML files named index.html in directories" 28 | @echo " singlehtml to make a single large HTML file" 29 | @echo " pickle to make pickle files" 30 | @echo " json to make JSON files" 31 | @echo " htmlhelp to make HTML files and a HTML help project" 32 | @echo " qthelp to make HTML files and a qthelp project" 33 | @echo " applehelp to make an Apple Help Book" 34 | @echo " devhelp to make HTML files and a Devhelp project" 35 | @echo " epub to make an epub" 36 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 37 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 38 | @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" 39 | @echo " text to make text files" 40 | @echo " man to make manual pages" 41 | @echo " texinfo to make Texinfo files" 42 | @echo " info to make Texinfo files and run them through makeinfo" 43 | @echo " gettext to make PO message catalogs" 44 | @echo " changes to make an overview of all changed/added/deprecated items" 45 | @echo " xml to make Docutils-native XML files" 46 | @echo " pseudoxml to make pseudoxml-XML files for display purposes" 47 | @echo " linkcheck to check all external links for integrity" 48 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 49 | @echo " coverage to run coverage check of the documentation (if enabled)" 50 | 51 | clean: 52 | rm -rf $(BUILDDIR)/* 53 | 54 | html: 55 | rm -rf $(BUILDDIR)/* 56 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 57 | @echo 58 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 59 | 60 | dirhtml: 61 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 62 | @echo 63 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 64 | 65 | singlehtml: 66 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 67 | @echo 68 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 69 | 70 | pickle: 71 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 72 | @echo 73 | @echo "Build finished; now you can process the pickle files." 74 | 75 | json: 76 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 77 | @echo 78 | @echo "Build finished; now you can process the JSON files." 79 | 80 | htmlhelp: 81 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 82 | @echo 83 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 84 | ".hhp project file in $(BUILDDIR)/htmlhelp." 85 | 86 | qthelp: 87 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 88 | @echo 89 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 90 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 91 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/sphinxcontrib-osexample.qhcp" 92 | @echo "To view the help file:" 93 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/sphinxcontrib-osexample.qhc" 94 | 95 | applehelp: 96 | $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp 97 | @echo 98 | @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." 99 | @echo "N.B. You won't be able to view it unless you put it in" \ 100 | "~/Library/Documentation/Help or install it in your application" \ 101 | "bundle." 102 | 103 | devhelp: 104 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 105 | @echo 106 | @echo "Build finished." 107 | @echo "To view the help file:" 108 | @echo "# mkdir -p $$HOME/.local/share/devhelp/sphinxcontrib-osexample" 109 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/sphinxcontrib-osexample" 110 | @echo "# devhelp" 111 | 112 | epub: 113 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 114 | @echo 115 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 116 | 117 | latex: 118 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 119 | @echo 120 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 121 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 122 | "(use \`make latexpdf' here to do that automatically)." 123 | 124 | latexpdf: 125 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 126 | @echo "Running LaTeX files through pdflatex..." 127 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 128 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 129 | 130 | latexpdfja: 131 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 132 | @echo "Running LaTeX files through platex and dvipdfmx..." 133 | $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja 134 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 135 | 136 | text: 137 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 138 | @echo 139 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 140 | 141 | man: 142 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 143 | @echo 144 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 145 | 146 | texinfo: 147 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 148 | @echo 149 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 150 | @echo "Run \`make' in that directory to run these through makeinfo" \ 151 | "(use \`make info' here to do that automatically)." 152 | 153 | info: 154 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 155 | @echo "Running Texinfo files through makeinfo..." 156 | make -C $(BUILDDIR)/texinfo info 157 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 158 | 159 | gettext: 160 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 161 | @echo 162 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 163 | 164 | changes: 165 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 166 | @echo 167 | @echo "The overview file is in $(BUILDDIR)/changes." 168 | 169 | linkcheck: 170 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 171 | @echo 172 | @echo "Link check complete; look for any errors in the above output " \ 173 | "or in $(BUILDDIR)/linkcheck/output.txt." 174 | 175 | doctest: 176 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 177 | @echo "Testing of doctests in the sources finished, look at the " \ 178 | "results in $(BUILDDIR)/doctest/output.txt." 179 | 180 | coverage: 181 | $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage 182 | @echo "Testing of coverage in the sources finished, look at the " \ 183 | "results in $(BUILDDIR)/coverage/python.txt." 184 | 185 | xml: 186 | $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml 187 | @echo 188 | @echo "Build finished. The XML files are in $(BUILDDIR)/xml." 189 | 190 | pseudoxml: 191 | $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml 192 | @echo 193 | @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." 194 | -------------------------------------------------------------------------------- /docs/_static/example.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/svx/sphinxcontrib-osexample/1cc4afcc6089083256aa642d9faa12352ef45d68/docs/_static/example.gif -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # sphinxcontrib-osexample documentation build configuration file, created by 4 | # sphinx-quickstart on Wed Dec 23 16:49:36 2015. 5 | # 6 | # This file is execfile()d with the current directory set to its 7 | # containing dir. 8 | # 9 | # Note that not all possible configuration values are present in this 10 | # autogenerated file. 11 | # 12 | # All configuration values have a default; values that are commented out 13 | # serve to show the default. 14 | 15 | import sys 16 | import os 17 | import shlex 18 | 19 | # If extensions (or modules to document with autodoc) are in another directory, 20 | # add these directories to sys.path here. If the directory is relative to the 21 | # documentation root, use os.path.abspath to make it absolute, like shown here. 22 | #sys.path.insert(0, os.path.abspath('.')) 23 | 24 | # -- General configuration ------------------------------------------------ 25 | 26 | # If your documentation needs a minimal Sphinx version, state it here. 27 | #needs_sphinx = '1.0' 28 | 29 | # Add any Sphinx extension module names here, as strings. They can be 30 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 31 | # ones. 32 | extensions = [ 33 | 'sphinx.ext.autodoc', 34 | 'sphinx.ext.doctest', 35 | 'sphinx.ext.intersphinx', 36 | 'sphinx.ext.todo', 37 | 'sphinx.ext.coverage', 38 | 'sphinx.ext.viewcode', 39 | ] 40 | 41 | # Add any paths that contain templates here, relative to this directory. 42 | templates_path = ['_templates'] 43 | 44 | # The suffix(es) of source filenames. 45 | # You can specify multiple suffix as a list of string: 46 | # source_suffix = ['.rst', '.md'] 47 | source_suffix = '.rst' 48 | 49 | # The encoding of source files. 50 | #source_encoding = 'utf-8-sig' 51 | 52 | # The master toctree document. 53 | master_doc = 'index' 54 | 55 | # General information about the project. 56 | project = u'sphinxcontrib-osexample' 57 | copyright = u'2015, svx' 58 | author = u'svx' 59 | 60 | # The version info for the project you're documenting, acts as replacement for 61 | # |version| and |release|, also used in various other places throughout the 62 | # built documents. 63 | # 64 | # The short X.Y version. 65 | version = u'0.1.0' 66 | # The full version, including alpha/beta/rc tags. 67 | release = u'0.1.0' 68 | 69 | # The language for content autogenerated by Sphinx. Refer to documentation 70 | # for a list of supported languages. 71 | # 72 | # This is also used if you do content translation via gettext catalogs. 73 | # Usually you set "language" from the command line for these cases. 74 | language = None 75 | 76 | # There are two options for replacing |today|: either, you set today to some 77 | # non-false value, then it is used: 78 | #today = '' 79 | # Else, today_fmt is used as the format for a strftime call. 80 | #today_fmt = '%B %d, %Y' 81 | 82 | # List of patterns, relative to source directory, that match files and 83 | # directories to ignore when looking for source files. 84 | exclude_patterns = ['_build'] 85 | 86 | # The reST default role (used for this markup: `text`) to use for all 87 | # documents. 88 | #default_role = None 89 | 90 | # If true, '()' will be appended to :func: etc. cross-reference text. 91 | #add_function_parentheses = True 92 | 93 | # If true, the current module name will be prepended to all description 94 | # unit titles (such as .. function::). 95 | #add_module_names = True 96 | 97 | # If true, sectionauthor and moduleauthor directives will be shown in the 98 | # output. They are ignored by default. 99 | #show_authors = False 100 | 101 | # The name of the Pygments (syntax highlighting) style to use. 102 | pygments_style = 'sphinx' 103 | 104 | # A list of ignored prefixes for module index sorting. 105 | #modindex_common_prefix = [] 106 | 107 | # If true, keep warnings as "system message" paragraphs in the built documents. 108 | #keep_warnings = False 109 | 110 | # If true, `todo` and `todoList` produce output, else they produce nothing. 111 | todo_include_todos = True 112 | 113 | 114 | # -- Options for HTML output ---------------------------------------------- 115 | 116 | # The theme to use for HTML and HTML Help pages. See the documentation for 117 | # a list of builtin themes. 118 | html_theme = 'alabaster' 119 | 120 | # Theme options are theme-specific and customize the look and feel of a theme 121 | # further. For a list of options available for each theme, see the 122 | # documentation. 123 | #html_theme_options = {} 124 | 125 | # Add any paths that contain custom themes here, relative to this directory. 126 | #html_theme_path = [] 127 | 128 | # The name for this set of Sphinx documents. If None, it defaults to 129 | # " v documentation". 130 | #html_title = None 131 | 132 | # A shorter title for the navigation bar. Default is the same as html_title. 133 | #html_short_title = None 134 | 135 | # The name of an image file (relative to this directory) to place at the top 136 | # of the sidebar. 137 | #html_logo = None 138 | 139 | # The name of an image file (within the static path) to use as favicon of the 140 | # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 141 | # pixels large. 142 | #html_favicon = None 143 | 144 | # Add any paths that contain custom static files (such as style sheets) here, 145 | # relative to this directory. They are copied after the builtin static files, 146 | # so a file named "default.css" will overwrite the builtin "default.css". 147 | html_static_path = ['_static'] 148 | 149 | # Add any extra paths that contain custom files (such as robots.txt or 150 | # .htaccess) here, relative to this directory. These files are copied 151 | # directly to the root of the documentation. 152 | #html_extra_path = [] 153 | 154 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 155 | # using the given strftime format. 156 | #html_last_updated_fmt = '%b %d, %Y' 157 | 158 | # If true, SmartyPants will be used to convert quotes and dashes to 159 | # typographically correct entities. 160 | #html_use_smartypants = True 161 | 162 | # Custom sidebar templates, maps document names to template names. 163 | #html_sidebars = {} 164 | 165 | # Additional templates that should be rendered to pages, maps page names to 166 | # template names. 167 | #html_additional_pages = {} 168 | 169 | # If false, no module index is generated. 170 | #html_domain_indices = True 171 | 172 | # If false, no index is generated. 173 | #html_use_index = True 174 | 175 | # If true, the index is split into individual pages for each letter. 176 | #html_split_index = False 177 | 178 | # If true, links to the reST sources are added to the pages. 179 | #html_show_sourcelink = True 180 | 181 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 182 | #html_show_sphinx = True 183 | 184 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 185 | #html_show_copyright = True 186 | 187 | # If true, an OpenSearch description file will be output, and all pages will 188 | # contain a tag referring to it. The value of this option must be the 189 | # base URL from which the finished HTML is served. 190 | #html_use_opensearch = '' 191 | 192 | # This is the file name suffix for HTML files (e.g. ".xhtml"). 193 | #html_file_suffix = None 194 | 195 | # Language to be used for generating the HTML full-text search index. 196 | # Sphinx supports the following languages: 197 | # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' 198 | # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' 199 | #html_search_language = 'en' 200 | 201 | # A dictionary with options for the search language support, empty by default. 202 | # Now only 'ja' uses this config value 203 | #html_search_options = {'type': 'default'} 204 | 205 | # The name of a javascript file (relative to the configuration directory) that 206 | # implements a search results scorer. If empty, the default will be used. 207 | #html_search_scorer = 'scorer.js' 208 | 209 | # Output file base name for HTML help builder. 210 | htmlhelp_basename = 'sphinxcontrib-osexampledoc' 211 | 212 | # -- Options for LaTeX output --------------------------------------------- 213 | 214 | latex_elements = { 215 | # The paper size ('letterpaper' or 'a4paper'). 216 | #'papersize': 'letterpaper', 217 | 218 | # The font size ('10pt', '11pt' or '12pt'). 219 | #'pointsize': '10pt', 220 | 221 | # Additional stuff for the LaTeX preamble. 222 | #'preamble': '', 223 | 224 | # Latex figure (float) alignment 225 | #'figure_align': 'htbp', 226 | } 227 | 228 | # Grouping the document tree into LaTeX files. List of tuples 229 | # (source start file, target name, title, 230 | # author, documentclass [howto, manual, or own class]). 231 | latex_documents = [ 232 | (master_doc, 'sphinxcontrib-osexample.tex', u'sphinxcontrib-osexample Documentation', 233 | u'svx', 'manual'), 234 | ] 235 | 236 | # The name of an image file (relative to this directory) to place at the top of 237 | # the title page. 238 | #latex_logo = None 239 | 240 | # For "manual" documents, if this is true, then toplevel headings are parts, 241 | # not chapters. 242 | #latex_use_parts = False 243 | 244 | # If true, show page references after internal links. 245 | #latex_show_pagerefs = False 246 | 247 | # If true, show URL addresses after external links. 248 | #latex_show_urls = False 249 | 250 | # Documents to append as an appendix to all manuals. 251 | #latex_appendices = [] 252 | 253 | # If false, no module index is generated. 254 | #latex_domain_indices = True 255 | 256 | 257 | # -- Options for manual page output --------------------------------------- 258 | 259 | # One entry per manual page. List of tuples 260 | # (source start file, name, description, authors, manual section). 261 | man_pages = [ 262 | (master_doc, 'sphinxcontrib-osexample', u'sphinxcontrib-osexample Documentation', 263 | [author], 1) 264 | ] 265 | 266 | # If true, show URL addresses after external links. 267 | #man_show_urls = False 268 | 269 | 270 | # -- Options for Texinfo output ------------------------------------------- 271 | 272 | # Grouping the document tree into Texinfo files. List of tuples 273 | # (source start file, target name, title, author, 274 | # dir menu entry, description, category) 275 | texinfo_documents = [ 276 | (master_doc, 'sphinxcontrib-osexample', u'sphinxcontrib-osexample Documentation', 277 | author, 'sphinxcontrib-osexample', 'One line description of project.', 278 | 'Miscellaneous'), 279 | ] 280 | 281 | # Documents to append as an appendix to all manuals. 282 | #texinfo_appendices = [] 283 | 284 | # If false, no module index is generated. 285 | #texinfo_domain_indices = True 286 | 287 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 288 | #texinfo_show_urls = 'footnote' 289 | 290 | # If true, do not generate a @detailmenu in the "Top" node's menu. 291 | #texinfo_no_detailmenu = False 292 | 293 | 294 | # Example configuration for intersphinx: refer to the Python standard library. 295 | intersphinx_mapping = {'https://docs.python.org/': None} 296 | -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | .. sphinxcontrib-osexample documentation master file, created by 2 | sphinx-quickstart on Wed Dec 23 16:49:36 2015. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | sphinxcontrib-osexample 7 | ======================= 8 | 9 | .. toctree:: 10 | :maxdepth: 2 11 | 12 | About 13 | ===== 14 | 15 | This is a simple extension that, when rendered as HTML, will fold multiple 16 | code blocks containing different operating systems administration examples into a single block 17 | which can be toggled from one to another using buttons. 18 | 19 | It's intended to be used for displaying package manager examples. 20 | (e.g., apt install or dnf install). 21 | 22 | This extension adds the ``example-code`` directive which adds a class to 23 | a container wrapping the code blocks that should be folded. The class allows 24 | the included Javascript and CSS to render the folded block and buttons. 25 | 26 | Currently supported are: Debian, Ubuntu, Fedora, CentOS, OSX 27 | 28 | Quick Example 29 | ------------- 30 | 31 | Source would look something like this:: 32 | 33 | .. example-code:: 34 | .. code-block:: Debian 35 | 36 | sudo apt install htop 37 | 38 | .. code-block:: Fedora 39 | 40 | sudo dnf install htop 41 | 42 | .. code-block:: OSX 43 | 44 | brew install htop 45 | 46 | 47 | This will create an output like this: 48 | 49 | .. image:: https://raw.githubusercontent.com/svx/sphinxcontrib-osexample/master/docs/_static/example.gif 50 | :alt: Example how it looks like as generated HTML 51 | 52 | 53 | Installation 54 | ------------ 55 | 56 | .. code-block:: bash 57 | 58 | $ pip install sphinxcontrib-osexample 59 | 60 | 61 | Enabling the extension in Sphinx 62 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 63 | 64 | Just add sphinxcontrib.examplecode to the list of extensions in the conf.py file. For example: 65 | 66 | .. code-block:: bash 67 | 68 | extensions = ['sphinxcontrib.osexample'] 69 | 70 | 71 | 72 | -------------------------------------------------------------------------------- /lexer/examplefiles/example.osexample: -------------------------------------------------------------------------------- 1 | Debian/Ubuntu 2 | ============= 3 | 4 | apt-get 5 | apt 6 | apt install 7 | apt-get install 8 | 9 | CentOS 10 | ======= 11 | 12 | yum 13 | yum install 14 | yum update 15 | yum check-update 16 | 17 | Fedora 18 | ====== 19 | 20 | dnf 21 | dnf install 22 | dnf update 23 | dnf check-update 24 | 25 | Homebrew 26 | ======== 27 | 28 | brew 29 | brew install 30 | brew update 31 | -------------------------------------------------------------------------------- /lexer/test-osexample.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | import re 3 | from pygments.lexer import RegexLexer, bygroups 4 | from pygments.token import Keyword, Number, Text, Comment 5 | 6 | __all__ = ['UbuntuLexer', 'CentosLexer', 'FedoraLexer'] 7 | 8 | class UbuntuLexer(RegexLexer): 9 | name = 'Ubuntu' 10 | aliases = ['ubuntu'] 11 | filenames = ['*.ubuntu'] 12 | 13 | tokens = { 14 | 'root': [ 15 | (r'\bapt\b', Keyword), 16 | (r'\b((apt-)?get\b)', Keyword), 17 | (r'\s', Text), 18 | (r'-', Text), 19 | (r'\S+', Keyword.Pseudo), 20 | (r'[;#].*', Comment.Single), 21 | ], 22 | } 23 | class CentosLexer(RegexLexer): 24 | name = 'Centos' 25 | aliases = ['centos'] 26 | filenames = ['*.ubuntu'] 27 | 28 | tokens = { 29 | 'root': [ 30 | (r'\byum\b', Keyword), 31 | (r'\b((yum)?update\b)', Keyword), 32 | (r'\b((yum)?install\b)', Keyword), 33 | (r'\b((yum-)?check\b)', Keyword), 34 | (r'\s', Text), 35 | (r'-', Text), 36 | (r'\S+', Keyword.Pseudo), 37 | (r'[;#].*', Comment.Single), 38 | ], 39 | } 40 | 41 | class FedoraLexer(RegexLexer): 42 | name = 'Fedora' 43 | aliases = ['fedora'] 44 | filenames = ['*.ubuntu'] 45 | 46 | tokens = { 47 | 'root': [ 48 | (r'\bdnf\b', Keyword), 49 | (r'\b((dnf)?update\b)', Keyword), 50 | (r'\b((dnf)?install\b)', Keyword), 51 | (r'\b((dnf-)?check\b)', Keyword), 52 | (r'\s', Text), 53 | (r'-', Text), 54 | (r'\S+', Keyword.Pseudo), 55 | (r'[;#].*', Comment.Single), 56 | ], 57 | } -------------------------------------------------------------------------------- /lexer/test.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | echo "running test" 3 | ../bin/pygmentize -O full -f html -o /tmp/example.html examplefiles/example.osexample 4 | 5 | echo "please open /tmp/example.html in your fav. browser" 6 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx 2 | -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [egg_info] 2 | tag_build = 3 | tag_date = false 4 | 5 | [aliases] 6 | release = egg_info -RDb '' 7 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | 3 | from setuptools import setup, find_packages 4 | 5 | def readme(): 6 | with open('README.rst') as f: 7 | return f.read() 8 | 9 | ''' 10 | This package contains the osexample Sphinx extension. 11 | 12 | This extension adds support for Operating systems code block 13 | widget to Sphinx. 14 | ''' 15 | 16 | requires = ['Sphinx>=1.0'] 17 | 18 | setup( 19 | name='sphinxcontrib-osexample', 20 | version='0.1.2.dev0', 21 | url='https://github.com/svx/sphinxcontrib-osexample', 22 | download_url='http://pypi.python.org/pypi/sphinxcontrib-osexample', 23 | license='BSD', 24 | author='Sven Strack', 25 | author_email='sven@so36.net', 26 | description='Sphinx extension for OS code-blocks', 27 | keywords = "Sphinx extension", 28 | long_description=readme(), 29 | zip_safe=False, 30 | classifiers=[ 31 | 'Development Status :: 4 - Beta', 32 | 'Environment :: Console', 33 | 'Environment :: Web Environment', 34 | 'Intended Audience :: Developers', 35 | 'License :: OSI Approved :: BSD License', 36 | 'Operating System :: OS Independent', 37 | 'Programming Language :: Python :: 2.7', 38 | 'Topic :: Documentation', 39 | 'Topic :: Utilities', 40 | ], 41 | platforms='any', 42 | packages=find_packages(), 43 | include_package_data=True, 44 | install_requires=requires, 45 | namespace_packages=['sphinxcontrib'], 46 | ) 47 | -------------------------------------------------------------------------------- /sphinxcontrib/__init__.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | sphinxcontrib 4 | ~~~~~~~~~~~~~ 5 | 6 | This package is a namespace package that contains all extensions 7 | distributed in the ``sphinx-contrib`` distribution. 8 | 9 | :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. 10 | :license: BSD, see LICENSE for details. 11 | """ 12 | 13 | __import__('pkg_resources').declare_namespace(__name__) 14 | 15 | -------------------------------------------------------------------------------- /sphinxcontrib/osexample.css: -------------------------------------------------------------------------------- 1 | ul.example-selector { 2 | display:block; 3 | list-style-type: none; 4 | height: 15px; 5 | margin: 0; 6 | padding: 0; 7 | } 8 | ul.example-selector li { 9 | display: block; 10 | cursor: pointer; 11 | font-weight: bold; 12 | margin: 0 5px 0 0; 13 | padding: 2px 3px; 14 | float: left; 15 | background-color: #999; 16 | color: #fff; 17 | -moz-border-radius: 5px; 18 | -webkit-border-radius: 5px; 19 | border-radius: 5px; 20 | -khtml-border-radius: 5px; 21 | } 22 | ul.example-selector li:hover { 23 | background-color: #777; 24 | } 25 | ul.example-selector li.selected { 26 | background-color: #555; 27 | } 28 | ul.example-selector li.selected:hover { 29 | background-color: #333; 30 | } 31 | -------------------------------------------------------------------------------- /sphinxcontrib/osexample.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Dynamic multiple language example code block. 3 | */ 4 | 5 | $(function() { 6 | 7 | $('div.example-code').each(function() { 8 | var example_sel = $('
    ', { class: "example-selector" }); 9 | var i = 0; 10 | $('div[class^="highlight-"]', this).each(function() { 11 | var sel_item = $('
  • ', { 12 | class: $(this).attr('class'), 13 | text: $(this).attr('class').substring(10) 14 | }); 15 | if (i++) { 16 | $(this).hide(); 17 | } else { 18 | sel_item.addClass('selected'); 19 | } 20 | example_sel.append(sel_item); 21 | $(this).addClass('example'); 22 | }); 23 | $(this).prepend(example_sel); 24 | example_sel = null; 25 | i = null; 26 | }); 27 | 28 | $('div.example-code ul.example-selector li').click(function(evt) { 29 | evt.preventDefault(); 30 | $('ul.example-selector li').removeClass('selected'); 31 | var sel_class = $(this).attr('class'); 32 | $('div.example').hide(); 33 | $('div.' + sel_class).show(); 34 | $('ul.example-selector li.' + sel_class).addClass('selected'); 35 | sel_class = null; 36 | }); 37 | 38 | }); 39 | 40 | -------------------------------------------------------------------------------- /sphinxcontrib/osexample.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | Examplecode specs 4 | ================= 5 | """ 6 | import os 7 | import re 8 | from docutils.parsers.rst import Directive 9 | from docutils import nodes 10 | from sphinx.util.osutil import copyfile 11 | from pygments.lexers import get_lexer_by_name 12 | from pygments.lexer import RegexLexer, bygroups 13 | from pygments.token import Keyword, Number, Text, Comment 14 | from pygments.util import ClassNotFound 15 | from sphinx.highlighting import lexers 16 | 17 | CSS_FILE = 'osexample.css' 18 | JS_FILE = 'osexample.js' 19 | 20 | __all__ = ['UbuntuLexer', 'CentosLexer', 'FedoraLexer', 'OSXLexer'] 21 | 22 | class UbuntuLexer(RegexLexer): 23 | name = 'Ubuntu' 24 | aliases = ['ubuntu', 'debian', 'Debian'] 25 | filenames = ['*.ubuntu'] 26 | 27 | tokens = { 28 | 'root': [ 29 | (r'\bapt\b', Keyword), 30 | (r'\b((apt-)?get\b)', Keyword), 31 | (r'\s', Text), 32 | (r'-', Text), 33 | (r'\S+', Keyword.Pseudo), 34 | (r'[;#].*', Comment.Single), 35 | ], 36 | } 37 | 38 | class CentosLexer(RegexLexer): 39 | name = 'Centos' 40 | aliases = ['centos', 'CentOS'] 41 | 42 | tokens = { 43 | 'root': [ 44 | (r'\byum\b', Keyword), 45 | (r'\b((yum)?update\b)', Keyword), 46 | (r'\b((yum)?install\b)', Keyword), 47 | (r'\b((yum-)?check\b)', Keyword), 48 | (r'\s', Text), 49 | (r'-', Text), 50 | (r'\S+', Keyword.Pseudo), 51 | (r'[;#].*', Comment.Single), 52 | ], 53 | } 54 | 55 | class FedoraLexer(RegexLexer): 56 | name = 'Fedora' 57 | aliases = ['fedora'] 58 | 59 | tokens = { 60 | 'root': [ 61 | (r'\bdnf\b', Keyword), 62 | (r'\b((dnf)?update\b)', Keyword), 63 | (r'\b((dnf)?install\b)', Keyword), 64 | (r'\b((dnf-)?check\b)', Keyword), 65 | (r'\s', Text), 66 | (r'-', Text), 67 | (r'\S+', Keyword.Pseudo), 68 | (r'[;#].*', Comment.Single), 69 | ], 70 | } 71 | 72 | class OSXLexer(RegexLexer): 73 | name = 'OSX' 74 | aliases = ['osx'] 75 | 76 | tokens = { 77 | 'root': [ 78 | (r'\bbrew\b', Keyword), 79 | (r'\b((brew)?install\b)', Keyword), 80 | (r'\b((brew)?create\b)', Keyword), 81 | (r'\b((brew)?edit\b)', Keyword), 82 | (r'\b((brew)?update\b)', Keyword), 83 | (r'\b((brew)?upgrade\b)', Keyword), 84 | (r'\b((brew)?cleanup\b)', Keyword), 85 | (r'\b((installer-)?pkg\b)', Keyword), 86 | (r'\s', Text), 87 | (r'-', Text), 88 | (r'\S+', Keyword.Pseudo), 89 | (r'[;#].*', Comment.Single), 90 | ], 91 | } 92 | 93 | class ExampleCodeDirective(Directive): 94 | """ 95 | This directive is intended to be used to contain a group of 96 | code blocks which are beingused to show OS examples for Ubuntu, Debian, 97 | Fedora, CentOS and OSX. 98 | When rendered as HTML the the examples will all be rolled up 99 | into a single display area with buttons to select between the different 100 | languages. 101 | """ 102 | 103 | has_content = True 104 | 105 | def run(self): 106 | self.assert_has_content() 107 | text = '\n'.join(self.content) 108 | node = nodes.container(text) 109 | node['classes'].append('example-code') 110 | self.add_name(node) 111 | self.state.nested_parse(self.content, self.content_offset, node) 112 | return [node] 113 | 114 | 115 | def add_assets(app): 116 | app.add_stylesheet(CSS_FILE) 117 | app.add_javascript(JS_FILE) 118 | 119 | def copy_assets(app, exception): 120 | if app.builder.name != 'html' or exception: 121 | return 122 | app.info('Copying osexample stylesheet/javascript... ', nonl=True) 123 | dest = os.path.join(app.builder.outdir, '_static', CSS_FILE) 124 | source = os.path.join(os.path.abspath(os.path.dirname(__file__)), CSS_FILE) 125 | copyfile(source, dest) 126 | dest = os.path.join(app.builder.outdir, '_static', JS_FILE) 127 | source = os.path.join(os.path.abspath(os.path.dirname(__file__)), JS_FILE) 128 | copyfile(source, dest) 129 | app.info('done') 130 | 131 | def setup(app): 132 | app.add_directive('example-code', ExampleCodeDirective) 133 | app.connect('builder-inited', add_assets) 134 | app.connect('build-finished', copy_assets) 135 | try: 136 | get_lexer_by_name('ubuntu') 137 | get_lexer_by_name('fedora') 138 | get_lexer_by_name('centos') 139 | except ClassNotFound: 140 | app.add_lexer('Ubuntu', UbuntuLexer()) 141 | app.add_lexer('Debian', UbuntuLexer()) 142 | app.add_lexer('Fedora', FedoraLexer()) 143 | app.add_lexer('CentOS', CentosLexer()) 144 | app.add_lexer('OSX', OSXLexer()) 145 | -------------------------------------------------------------------------------- /tox.ini: -------------------------------------------------------------------------------- 1 | ## configuration for tox 2 | 3 | ## tox automates running certain tasks within virtualenvs. The following 4 | ## tox configuration outlines a basic setup for running unit tests and 5 | ## building sphinx docs in separate virtual environments. Give it a try! 6 | 7 | [tox] 8 | envlist=python,doc 9 | 10 | # test running 11 | [testenv:python] 12 | deps= 13 | ## if you use nose for test running 14 | # nose 15 | ## if you use py.test for test running 16 | # pytest 17 | commands= 18 | ## run tests with py.test 19 | # py.test [] 20 | ## run tests with nose 21 | # nose 22 | 23 | [testenv:doc] 24 | deps= 25 | sphinx 26 | # add all Sphinx extensions and other dependencies required to build your docs 27 | commands= 28 | ## test links 29 | # sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees doc {envtmpdir}/linkcheck 30 | ## test html output 31 | # sphinx-build -W -b html -d {envtmpdir}/doctrees doc {envtmpdir}/html 32 | 33 | --------------------------------------------------------------------------------