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/tmp77vvd1mr
Docs files:      11 rst files with 19.53 kB
Docs setup:      0.07 s

Deps setup:      22.40 s
Matplotlib is building the font cache; this may take a moment.

Build files:     100 files with 6471.09 kB
File max️:        2208.66 kB by 
/tmp/tmp77vvd1mr/_build/_static/sphinx-needs/libs/html/datatables.min.js
File min:        0.01 kB by /tmp/tmp77vvd1mr/_build/_static/README
File Ø:          64.71 kB (0.43 s)
Reading time:    0.31 s
Writing time:    1.94 s
Build Duration:  42.79 s
─────────────────────────────────── RESULTS ────────────────────────────────────
╭───────────────┬────────────╮
│       #       │   Run 1    │
├───────────────┼────────────┤
│    runtime    │   42.79    │
│    project    │   needs    │
│               │            │
│    sphinx     │    5.1     │
│     depth     │     1      │
│   parallel    │     1      │
│     pages     │     10     │
│    builder    │    html    │
│    dummies    │     10     │
│     needs     │     10     │
│    folders    │     0      │
│  needtables   │     2      │
│               │            │
│  #needtables  │     20     │
│   #indexes    │     1      │
│    #pages     │     10     │
│    #needs     │    100     │
│   #folders    │     0      │
│   #dummies    │    100     │
│               │            │
│ writing time  │   1.94 s   │
│ avg file size │  64.71 kB  │
│    # files    │    100     │
│ avg file time │   0.43 s   │
│ min file size │  0.01 kB   │
│ max file size │ 2208.66 kB │
│  folder size  │ 6471.09 kB │
│ reading time  │   0.31 s   │
│               │            │
╰───────────────┴────────────╯

Overall runtime: 42.79 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}}
sphinx-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



# -- 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 = ["sphinx_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 %}