Package: jssphinx
Improve developer experience:
Write better docs. Stay concise. Never miss a detail.jsphinxhelps you to achieve what’s mentioned above.
You could see it as a mix of loosely coupled software components and
guidelines to make things perfect.Let me ask you a couple of conceptually connected questions:Do you write documentation?If you do, do you provide code examples along?Are you able to test them? Do you want to?Do you struggle making examples compact, yet fully functional?And do you want to learn how?What if I tell you that there’s an easy, non-intrusive solution?
It doesn’t reinvent the wheel; just leverages what’s already there.Move on to thedemossection to see it in action.DemosSee the list of available demos below. Pick a demo and from within the example
page, click on anySee the full examplelink to see how it works.alabaster demofuro demopydata-sphinx-theme demosphinx-book-theme demosphinx-bootstrap demosphinx-material demosphinx-rtd-theme demofaker-file documentationImpressed? Want to know how it works?Under the hoodjsphinx-downloaddirectiveSphinxis a documentation generator. It has many directives, among which
the.. literalinclude::, which allows us to include content of a file
directly into your documentation... literalinclude::itself has a:lines:option, which allows us to
specify which parts of the code to show. That’s what we use to keep the
primary focus on the most important parts of the code, reducing cognitive
load for the reader.Consider the following code example stored in a
file_static/py/faker_file_docx_1.py:importos# Required importsfromfakerimportFakerfromfaker_file.providers.docx_fileimportDocxFileProviderFAKER=Faker()# Initialize FakerFAKER.add_provider(DocxFileProvider)# Register DocxFileProvider# Generate DOCX filedocx_file=FAKER.docx_file()# Test things outprint(docx_file)print(docx_file.data["filename"])assertos.path.exists(docx_file.data["filename"])See the following snippet:..literalinclude::_static/py/faker_file_docx_1.py:language:python:lines:3-11The above mentioned snippet will be rendered as follows:# Required importsfromfakerimportFakerfromfaker_file.providers.docx_fileimportDocxFileProviderFAKER=Faker()# Initialize FakerFAKER.add_provider(DocxFileProvider)# Register DocxFileProvider# Generate DOCX filedocx_file=FAKER.docx_file()However, we also understand the importance of the broader context. For that
we use the:download:directive, which allows us to create a downloadable
link to a file (the same file we already included into the documentation
using.. literalinclude::). By that we ensure that those interested in the
complete code can easily access it.See the following snippet:..container::jsphinx-download*See the full example*:download:`here <_static/py/faker_file_docx_1.py>`The above mentioned snippet will be produce the following HTML:<pclass="jsphinx-download"><em>See the full example</em><aclass="reference download internal"href="_static/py/faker_file_docx_1.py"><spanclass="pre">here</span></a></p>See thejsphinx-download demoto see how it’s rendered.This is wherejsphinxsteps in. Using provided JavaScript,
we hook to the links generated by the:download:directive and instead
of downloading the content, show it in-line, right in place.Note, that although.. container::jsphinx-downloadtechnically
isn’t strictly required, it wraps our link into an element withjsphinx-downloadclass so that we can safely hook to all underlying
download links without a risk to cause unwanted behavior for other places
where you might have used:download:directive for other purposes.Finally,PrismJSsyntax highlighter is used to beautify the code and make
it look close to the code highlighting of yourSphinxtheme of choice.jsphinx-toggle-emphasisdirectiveAnother popularSphinxdirective is the..code-block::, which enables
us to display code blocks within your documentation.The..code-block::directive itself has a:emphasize-lines:option,
which is particularly useful for highlighting specific lines of code within
the code block. This helps to draw attention to most important  parts of the
code and helps the reader to understand the code.Consider the following example:..container::jsphinx-toggle-emphasis..code-block::python:emphasize-lines:3,6,8from faker import Faker# Import the file provider we want to usefrom faker_file.providers.txt_file import TxtFileProviderFAKER = Faker()  # Initialise Faker instanceFAKER.add_provider(TxtFileProvider)  # Register the file providertxt_file = FAKER.txt_file()  # Generate a TXT fileSee thejsphinx-toggle-emphasis demoto see how it’s rendered.jsphinxwill add a link to each.. container::jsphinx-toggle-emphasisblock for toggling the visibility of non-emphasized elements.ThemesPrismJSthemes based onSphinx’s aesthetics:alabaster(key:alabaster,alabaster demo)furo(key:furo,furo demo)pydata-sphinx-theme(key:pydata_sphinx_theme,pydata-sphinx-theme demo)sphinx-book-theme(key:sphinx_book_theme,sphinx-book-theme demo)sphinx-bootstrap-theme(key:bootstrap,sphinx-bootstrap demo)sphinx-material(key:sphinx_material,sphinx-material demo)sphinx-rtd-theme(key:sphinx_rtd_theme,sphinx-rtd-theme demo)InstallationVia CDN (jsDelivr)To use both the theme and adapter in your HTML:<!-- CSS for PrismJS Sphinx RTD theme --><linkhref="https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/css/sphinx_rtd_theme.css"rel="stylesheet"><!-- JS for PrismJS Sphinx Adapter --><scriptsrc="https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/js/download_adapter.js"></script>Sphinx integrationConfigurationTo integrate both into yourSphinxproject, add the following in
yourconf.py:# ************************************************************# ************************** The theme ***********************# ************************************************************html_theme="sphinx_rtd_theme"# ************************************************************# ***************** Additional JS/CSS files ******************# ************************************************************html_css_files=[# ..."https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/css/sphinx_rtd_theme.css",# ...]html_js_files=[# ..."https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/js/download_adapter.js",# ...]A complete configuration example, together with loadedPrismJSand the
toolbar with plugins, would look as follows:prismjs_base="//cdnjs.cloudflare.com/ajax/libs/prism/1.29.0"html_css_files=[f"{prismjs_base}/themes/prism.min.css",f"{prismjs_base}/plugins/toolbar/prism-toolbar.min.css","https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/css/sphinx_rtd_theme.css",]html_js_files=[f"{prismjs_base}/prism.min.js",f"{prismjs_base}/plugins/autoloader/prism-autoloader.min.js",f"{prismjs_base}/plugins/toolbar/prism-toolbar.min.js",f"{prismjs_base}/plugins/copy-to-clipboard/prism-copy-to-clipboard.min.js","https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/js/download_adapter.js",]You can also use otherSphinxthemes, such asalabaster,furo,pydata-sphinx-theme,sphinx-book-theme,sphinx-bootstrap-theme,sphinx-materialorsphinx-rtd-theme.Make sure to specify appropriate value (theme key) inhtml_theme,
as follows (pick one):html_theme="alabaster"html_theme="bootstrap"html_theme="furo"html_theme="pydata_sphinx_theme"html_theme="sphinx_book_theme"html_theme="sphinx_material"html_theme="sphinx_rtd_theme"Finally, make sure to specify correct path to the desired theme:html_css_files=[# ...f"https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/css/{html_theme}.css",]Testing your documentationAll code snippets of this repository can be tested withpytestas follows:pytestThepytesttest-runner finds tests in thedocs/test_docs.pymodule,
which is responsible for dynamical execution of Python files located in thedocs/_static/py/directory.This is howdocs/test_docs.pycould look:frompathlibimportPathimportpytest# Walk through the directory and all subdirectories for .py filesexample_dir=Path("docs/_static/py")py_files=sorted([str(p)forpinexample_dir.rglob("*.py")])defexecute_file(file_path):"""Dynamic test function."""global_vars={}withopen(file_path,"r")asf:code=f.read()exec(code,global_vars)@pytest.mark.parametrize("file_path",py_files)deftest_dynamic_files(file_path):execute_file(file_path)LicenseMITSupportFor security issues contact me at the e-mail given in theAuthorsection.For overall issues, go toGitHub issues.AuthorArtur Barseghyanartur.barseghyan@gmail.com.