ClammingPy 1.8

https://sourceforge.net/projects/clamming/

Module clamming

Class ExportOptions

Description

Store the options and content for an export to documented files.

ExportOptions is a data class, used to store options and content for exporting a documented file. It provides methods to set and get various information such as software name, copyright, icon, title, favicon, and theme. It also allows setting the names of the next and previous classes or modules for generating a table of contents (HTML only).

Example
 >>> h = ExportOptions()
 >>> h.software = "Clamming"
 >>> h.theme = "light"
 >>> html_head = h.get_head()
 >>> html_nav = h.get_nav()
 >>> html_footer = h.get_footer()

Constructor

Create a documentation export system for a ClamsPack.

Main functionalities:

  • Store options and content for exporting a standalone file;
  • Set and get HTML information such as software name, copyright, icon, title, favicon, and theme;
  • Set the names of the next and previous classes or modules for generating a table of contents.
View Source
def __init__(self):
    """Create a documentation export system for a ClamsPack.

    Main functionalities:

    - Store options and content for exporting a standalone file;
    - Set and get HTML information such as software name, copyright, icon, title, favicon, and theme;
    - Set the names of the next and previous classes or modules for generating a table of contents.

    """
    self.__readme = True
    self.__software = ExportOptions.DEFAULT_SOFTWARE
    self.__copyright = ExportOptions.DEFAULT_COPYRIGHT
    self.__url = ExportOptions.DEFAULT_URL
    self.__icon = ExportOptions.DEFAULT_ICON
    self.__title = ExportOptions.DEFAULT_TITLE
    self.__favicon = ExportOptions.DEFAULT_FAVICON
    self.__theme = ExportOptions.DEFAULT_THEME
    self.__statics = ExportOptions.DEFAULT_STATICS
    self.__wexa_statics = ExportOptions.DEFAULT_WEXA_STATICS
    self.__next_class = None
    self.__prev_class = None
    self.__next_pack = None
    self.__prev_pack = None

Public functions

get_add_readme

Return whether the README of library is added or not.

View Source
def get_add_readme(self) -> bool:
    """Return whether the README of library is added or not."""
    return self.__readme

set_add_readme

Set whether the README of library is added or not.

Parameters
  • readme: (bool) whether the README is added or not.
View Source
def set_add_readme(self, readme: bool) -> NoReturn:
    """Set whether the README of library is added or not.

        :param readme: (bool) whether the README is added or not.

        """
    self.__readme = bool(readme)

get_software

Return the name of the software.

View Source
def get_software(self) -> str:
    """Return the name of the software."""
    return self.__software

set_software

Set a software name.

Parameters
  • name: (str) Name of the documented software
Raises
  • TypeError: Given name is not a string
View Source
def set_software(self, name: str=DEFAULT_SOFTWARE) -> NoReturn:
    """Set a software name.

        :param name: (str) Name of the documented software
        :raises: TypeError: Given name is not a string

        """
    if isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' for the HTMLDocExport.software. Got {} instead.".format(name))
    self.__software = name

get_url

Return the url of the software.

View Source
def get_url(self) -> str:
    """Return the url of the software."""
    return self.__url

set_url

Set a software url.

Parameters
  • name: (str) URL of the documented software
Raises
  • TypeError: Given name is not a string
View Source
def set_url(self, name: str='') -> NoReturn:
    """Set a software url.

        :param name: (str) URL of the documented software
        :raises: TypeError: Given name is not a string

        """
    if isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' for the HTMLDocExport.url. Got {} instead.".format(name))
    self.__url = name

get_copyright

Return the copyright of the HTML page.

View Source
def get_copyright(self) -> str:
    """Return the copyright of the HTML page."""
    return self.__copyright

set_copyright

Set a copyright text, added to the footer of the page.

Parameters
  • text: (str) Copyright of the documented software
Raises
  • TypeError: Given text is not a string
View Source
def set_copyright(self, text: str=DEFAULT_COPYRIGHT) -> NoReturn:
    """Set a copyright text, added to the footer of the page.

        :param text: (str) Copyright of the documented software
        :raises: TypeError: Given text is not a string

        """
    if isinstance(text, (str, bytes)) is False:
        raise TypeError("Expected a 'str' for the HTMLDocExport.copyright. Got {} instead.".format(text))
    self.__copyright = text

get_icon

Return the icon filename of the software.

View Source
def get_icon(self) -> str:
    """Return the icon filename of the software."""
    return self.__icon

set_icon

Set an icon filename.

Parameters
  • name: (str) Filename of the icon of the documented software
Raises
  • TypeError: Given name is not a string
View Source
def set_icon(self, name: str=DEFAULT_ICON) -> NoReturn:
    """Set an icon filename.

        :param name: (str) Filename of the icon of the documented software
        :raises: TypeError: Given name is not a string

        """
    if isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' for the HTMLDocExport.icon. Got {} instead.".format(name))
    self.__icon = name

get_title

Return the title of the HTML page.

View Source
def get_title(self) -> str:
    """Return the title of the HTML page."""
    return self.__title

set_title

Set a title to the output HTML pages.

Parameters
  • text: (str) Title of the HTML pages
Raises
  • TypeError: Given text is not a string
View Source
def set_title(self, text: str=DEFAULT_TITLE) -> NoReturn:
    """Set a title to the output HTML pages.

        :param text: (str) Title of the HTML pages
        :raises: TypeError: Given text is not a string

        """
    if isinstance(text, (str, bytes)) is False:
        raise TypeError("Expected a 'str' for the HTMLDocExport.title. Got {} instead.".format(text))
    self.__title = text

get_statics

Return the static path of the CSS, JS, etc.

View Source
def get_statics(self) -> str:
    """Return the static path of the CSS, JS, etc."""
    return self.__statics

set_statics

Set the static path of the customs CSS, JS, etc.

Parameters
  • name: (str) Path of the static elements
Raises
  • TypeError: Given name is not a string
View Source
def set_statics(self, name: str=DEFAULT_STATICS) -> NoReturn:
    """Set the static path of the customs CSS, JS, etc.

        :param name: (str) Path of the static elements
        :raises: TypeError: Given name is not a string

        """
    if isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' for the HTMLDocExport.statics. Got {} instead.".format(name))
    self.__statics = name

get_wexa_statics

Return the static path of the CSS, JS, etc. of Whakerexa.

View Source
def get_wexa_statics(self) -> str:
    """Return the static path of the CSS, JS, etc. of Whakerexa. """
    return self.__wexa_statics

set_wexa_statics

Set the static path of the customs CSS, JS, etc. of Whakerexa.

Parameters
  • name: (str) Path of the static elements
Raises
  • TypeError: Given name is not a string
View Source
def set_wexa_statics(self, name: str=DEFAULT_WEXA_STATICS) -> NoReturn:
    """Set the static path of the customs CSS, JS, etc. of Whakerexa.

        :param name: (str) Path of the static elements
        :raises: TypeError: Given name is not a string

        """
    if isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' for the HTMLDocExport.wexa_statics. Got {} instead.".format(name))
    self.__wexa_statics = name

get_favicon

Return the favicon filename of the HTML pages.

View Source
def get_favicon(self) -> str:
    """Return the favicon filename of the HTML pages."""
    return self.__favicon

set_favicon

Set a favicon to the output HTML pages.

Parameters
  • name: (str) Favicon of the HTML pages
Raises
  • TypeError: Given name is not a string
View Source
def set_favicon(self, name: str=DEFAULT_FAVICON) -> NoReturn:
    """Set a favicon to the output HTML pages.

        :param name: (str) Favicon of the HTML pages
        :raises: TypeError: Given name is not a string

        """
    if isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' for the HTMLDocExport.favicon. Got {} instead.".format(name))
    self.__favicon = name

get_theme

Return the theme of the HTML page.

View Source
def get_theme(self) -> str:
    """Return the theme of the HTML page."""
    return self.__theme

set_theme

Set a theme name.

Parameters
  • name: (str) Name of the theme of the HTML pages
Raises
  • TypeError: Given name is not a string
View Source
def set_theme(self, name: str=DEFAULT_THEME) -> NoReturn:
    """Set a theme name.

        :param name: (str) Name of the theme of the HTML pages
        :raises: TypeError: Given name is not a string

        """
    if isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' for the HTMLDocExport.theme. Got {} instead.".format(name))
    self.__theme = name

get_next_class

Return the name of the next documented class.

View Source
def get_next_class(self) -> str:
    """Return the name of the next documented class."""
    return self.__next_class

set_next_class

Set the name of the next documented class.

Parameters
  • name: (str|None) Name of the next documented class
Raises
  • TypeError: Given name is not a string
View Source
def set_next_class(self, name: str | None=None) -> NoReturn:
    """Set the name of the next documented class.

        :param name: (str|None) Name of the next documented class
        :raises: TypeError: Given name is not a string

        """
    if name is not None and isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' or None for the HTMLDocExport.next_class. Got {} instead.".format(name))
    self.__next_class = name

get_prev_class

Return the name of the previous documented class, for the ToC.

View Source
def get_prev_class(self) -> str:
    """Return the name of the previous documented class, for the ToC."""
    return self.__prev_class

set_prev_class

Set the name of the previous documented class.

Parameters
  • name: (str|None) Name of the previous documented class
Raises
  • TypeError: Given name is not a string
View Source
def set_prev_class(self, name: str | None=None) -> NoReturn:
    """Set the name of the previous documented class.

        :param name: (str|None) Name of the previous documented class
        :raises: TypeError: Given name is not a string

        """
    if name is not None and isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' or None for the HTMLDocExport.prev_class. Got {} instead.".format(name))
    self.__prev_class = name

get_next_module

Return the name of the next documented module.

View Source
def get_next_module(self) -> str:
    """Return the name of the next documented module."""
    return self.__next_pack

set_next_module

Set the name of the next documented module.

Parameters
  • name: (str|None) Name of the next documented module
Raises
  • TypeError: Given name is not a string
View Source
def set_next_module(self, name: str | None=None) -> NoReturn:
    """Set the name of the next documented module.

        :param name: (str|None) Name of the next documented module
        :raises: TypeError: Given name is not a string

        """
    if name is not None and isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' or None for the HTMLDocExport.next_module. Got {} instead.".format(name))
    self.__next_pack = name

get_prev_module

Return the name of the previous documented module, for the ToC.

View Source
def get_prev_module(self) -> str:
    """Return the name of the previous documented module, for the ToC."""
    return self.__prev_pack

set_prev_module

Set the name of the previous documented module.

Parameters
  • name: (str|None) Name of the previous documented module
Raises
  • TypeError: Given name is not a string
View Source
def set_prev_module(self, name: str | None=None) -> NoReturn:
    """Set the name of the previous documented module.

        :param name: (str|None) Name of the previous documented module
        :raises: TypeError: Given name is not a string

        """
    if name is not None and isinstance(name, (str, bytes)) is False:
        raise TypeError("Expected a 'str' or None for the HTMLDocExport.prev_module. Got {} instead.".format(name))
    self.__prev_pack = name

get_head

Return the HTML 'head' of the page.

View Source
def get_head(self) -> str:
    """Return the HTML 'head' of the page."""
    return ExportOptions.HTML_HEAD.format(TITLE=self.__title, FAVICON=self.__favicon, THEME=self.__theme, STATICS=self.__statics, WEXA_STATICS=self.__wexa_statics)

get_header

Return the 'header' of the HTML->body of the page.

View Source
def get_header(self) -> str:
    """Return the 'header' of the HTML->body of the page."""
    h = list()
    h.append('    <header>')
    h.append(ExportOptions.HTML_BUTTONS_ACCESSIBILITY.format(WEXA_STATICS=self.__wexa_statics))
    if len(self.__software) > 0:
        h.append('    <h1>{SOFTWARE}</h1>'.format(SOFTWARE=self.__software))
    if len(self.__icon) > 0:
        h.append('        <p><img class="small-logo" src="{STATICS}/{ICON}" alt="Software logo"/></p>'.format(STATICS=self.__statics, ICON=self.__icon))
    if len(self.__url) > 0:
        h.append('        <p><a class="external-link" href="{URL}">{URL}</a></p>'.format(URL=self.__url))
    h.append('    </header>')
    return '\n'.join(h)

get_nav

Return the 'nav' of the HTML->body of the page.

View Source
def get_nav(self) -> str:
    """Return the 'nav' of the HTML->body of the page."""
    nav = list()
    nav.append('<nav id="nav-book" class="side-nav">')
    if self.__software == ExportOptions.DEFAULT_SOFTWARE:
        nav.append('    <h1>Documentation</h1>')
    else:
        nav.append('    <h1>{SOFTWARE}</h1>'.format(SOFTWARE=self.__software))
    if len(self.__icon) > 0:
        nav.append('    <img class="small-logo center" src="{STATICS}/{ICON}" alt=""/>'.format(STATICS=self.__statics, ICON=self.__icon))
    if len(self.__url) > 0:
        nav.append('        <p><a class="external-link" href="{URL}">{URL}</a></p>'.format(URL=self.__url))
    nav.append('    <ul>')
    nav.append(ExportOptions.__nav_link('&crarr; Prev. Module', self.__prev_pack))
    nav.append(ExportOptions.__nav_link('&uarr; Prev. Class', self.__prev_class))
    nav.append(ExportOptions.__nav_link('&#8962; Index', 'index.html'))
    nav.append(ExportOptions.__nav_link('&darr; Next Class', self.__next_class))
    nav.append(ExportOptions.__nav_link('&rdsh; Next Module', self.__next_pack))
    nav.append('    </ul>')
    nav.append('    <h2>Table of Contents</h2>')
    nav.append('    <ul id="toc"></ul>')
    nav.append('    <hr>')
    nav.append('    <p><small>Automatically created</small></p><p><small>by <a class="external-link" href="https://clamming.sf.net">ClammingPy</a></small></p>')
    nav.append('</nav>')
    return '\n'.join(nav)

get_footer

Return the 'footer' of the HTML->body of the page.

View Source
def get_footer(self) -> str:
    """Return the 'footer' of the HTML->body of the page."""
    return ExportOptions.HTML_FOOTER.format(COPYRIGHT=self.__copyright)

Protected functions

__nav_link

View Source
@staticmethod
def __nav_link(text: str, link: str | None) -> str:
    if link is None:
        a = 'aria-disabled="true"'
    else:
        a = 'href="{:s}"'.format(link)
    return '<li><a role="button" tabindex="0" {LINK}> {TEXT}</a></li>'.format(LINK=a, TEXT=text)