Needs¶
A Sphinx-Needs specific project to test the performance with different amounts of needs and needtables.
Parameters¶
- needs:
Number of maximum needs
- needtables:
Number of maximum needtables
- dummies:
Number of standard rst dummies
- pages:
Number of additional pages with needs
- parallel:
Number of parallel processes to use. Same as -j for sphinx-build
- sphinx:
Sphinx version to use
For the default values of the above parameters, please take a look into the performance.py file.
Information¶
- #needs:
Overall amount of needs
- #needtables:
Overall amount of needtables
- #dummies:
Overall amount of dummies
Run¶
$ sphinx-performance --project needs
Running 1 test configurations.
Running 1 test configurations.
─────────────────────────────────── Run 1/1 ────────────────────────────────────
Project: needs
Core/s: 1
Builder: html
Config: sphinx: 5.1, needs: 10, needtables: 2, dummies: 10, pages: 10,
folders: 0, depth: 1
Info: #needs: 100, #needtables: 20, #dummies: 100, #pages: 10,
#indexes: 1, #folders: 0
Docs path: /tmp/tmp1n60xye1
Docs files: 11 rst files with 19.53 kB
Docs setup: 0.06 s
Deps setup: 15.96 s
Build files: 100 files with 6646.02 kB
File max️: 2208.66 kB by
/tmp/tmp1n60xye1/_build/_static/sphinx-needs/libs/html/datatables.min.js
File min: 0.01 kB by /tmp/tmp1n60xye1/_build/_static/README
File Ø: 66.46 kB (0.06 s)
Reading time: 0.26 s
Writing time: 1.75 s
Build Duration: 6.04 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬────────────╮
│ # │ Run 1 │
├───────────────┼────────────┤
│ runtime │ 6.04 │
│ project │ needs │
│ │ │
│ pages │ 10 │
│ dummies │ 10 │
│ needtables │ 2 │
│ folders │ 0 │
│ builder │ html │
│ depth │ 1 │
│ needs │ 10 │
│ parallel │ 1 │
│ sphinx │ 5.1 │
│ │ │
│ #dummies │ 100 │
│ #indexes │ 1 │
│ #pages │ 10 │
│ #folders │ 0 │
│ #needs │ 100 │
│ #needtables │ 20 │
│ │ │
│ max file size │ 2208.66 kB │
│ avg file size │ 66.46 kB │
│ folder size │ 6646.02 kB │
│ avg file time │ 0.06 s │
│ reading time │ 0.26 s │
│ min file size │ 0.01 kB │
│ writing time │ 1.75 s │
│ # files │ 100 │
│ │ │
╰───────────────┴────────────╯
Overall runtime: 6.04 seconds.
Files¶
performance.py¶
parameters = {
"sphinx": "5.1",
"needs": 10,
"needtables": 2,
"dummies": 10,
"pages": 10,
"folders": 0,
"depth": 1
}
info = {
"#needs": "{{needs * page_amount}}",
"#needtables": "{{needtables * page_amount}}",
"#dummies": "{{dummies * page_amount}}",
'#pages': "{{page_amount}}",
'#indexes': "{{index_amount}}",
'#folders': "{{folders ** depth}}"
}
references = {
"small": {
"sphinx": "5.1",
"needs": 10,
"needtables": 2,
"dummies": 10,
"pages": 10,
"folders": 10,
"depth": 1
},
"medium": {
"sphinx": "5.1",
"needs": 10,
"needtables": 2,
"dummies": 10,
"pages": 10,
"folders": 10,
"depth": 2
},
"large": {
"sphinx": "5.1",
"needs": 30,
"needtables": 2,
"dummies": 50,
"pages": 10,
"folders": 10,
"depth": 3
},
}
requirements.template¶
sphinx=={{sphinx}}
sphinxcontrib-needs
sphinxcontrib-plantuml
conf.template¶
# -*- coding: utf-8 -*-
#
# needs test docs documentation build configuration file, created by
# sphinx-quickstart on Tue Mar 28 11:37:14 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
from docutils.parsers.rst import directives
sys.path.insert(0, os.path.abspath("../../sphinxcontrib"))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ["sphinxcontrib.needs"]
needs_profiling = ["needtable"]
{% if not basic %}
needs_types = [
dict(directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node"),
dict(directive="story", title="User Story", prefix="US_", color="#BFD8D2", style="node"),
dict(directive="spec", title="Specification", prefix="SP_", color="#FEDCD2", style="node"),
dict(directive="impl", title="Implementation", prefix="IM_", color="#DF744A", style="node"),
dict(directive="test", title="Test Case", prefix="TC_", color="#DCB239", style="node"),
]
needs_id_regex = "^[A-Z0-9_]{3,}"
needs_extra_options = ["number"]
{% endif %}
plantuml = "java -jar %s" % os.path.join(os.path.dirname(__file__), "..", "..", "docs", "utils", "plantuml.jar")
plantuml_output_format = "svg"
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = ".rst"
# The master toctree document.
master_doc = "index"
# General information about the project.
project = "needs test docs"
copyright = "2017, team useblocks"
author = "team useblocks"
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = "1.0"
# The full version, including alpha/beta/rc tags.
release = "1.0"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "alabaster"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = "needstestdocsdoc"
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, "needstestdocs.tex", "needs test docs Documentation", "team useblocks", "manual"),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [(master_doc, "needstestdocs", "needs test docs Documentation", [author], 1)]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(
master_doc,
"needstestdocs",
"needs test docs Documentation",
author,
"needstestdocs",
"One line description of project.",
"Miscellaneous",
),
]
index.template¶
Performance test
================
Config
------
:pages: {{pages}}
:dummies: {{dummies}}
:needs: {{needs}}
:needtables: {{needtables}}
:keep: {{keep}}
:browser: {{browser}}
:debug: {{debug}}
Content
-------
.. contents::
.. toctree::
{%- for page in range(pages) %}
page_{{page}}
{%- endfor -%}
{%- if has_folders %}
{%- for folder in range(folders) %}
folder_{{folder}}/index
{%- endfor -%}
{% endif -%}
page.template¶
{{ title}}
{{ "=" * title|length }}
Test Data
---------
Dummies
~~~~~~~
Amount of dummies: **{{dummies}}**
{% for n in range(dummies) %}
**Dummy {{n}}**
.. note:: This is dummy {{n}}
And some **dummy** *text* for dummy {{n}}
{% endfor %}
Needs
~~~~~
Amount of needs: **{{needs}}**
{% for n in range(needs) %}
.. req:: Test Need Page {{ page }} {{n}}
:id: R_{{global_page}}_{{n}}
{% if not basic %} :number: {{n}}{% endif %}
:links: R_{{global_page}}_{{needs-n-1}}
{% endfor %}
Needtable
~~~~~~~~~
Amount of needtables: **{{needtables}}**
{% if basic %}
.. needtable::
:show_filters:
:columns: id, title, number, links
{% else %}
{% for n in range(needtables) %}
.. needtable::
:show_filters:
:filter: int(number)**3 > 0 or len(links) > 0
:columns: id, title, number, links
{% endfor %}
{% endif %}
