epythet.tools¶

Tools to diagnose (and sometimes, repair) documentation

Examples

>>> repair_package(PY_FILES_DIRECTORY)

If you have tec (pip install tec) installed, you can even input a module object:

>>> import epythet
>>> number_of_problems = repair_package(epythet)
---> This is just a diagnosis: No files are being written to
setup_docsrc.py                           : #problems: 0
config_parser.py                          : #problems: 0
...
docs_gen.py                               : #problems: 0

As the print out header indicated, this is just a diagnosis of problems found for each module, and returns the total number of problems. It’s advised to do this, then have a look at the problems using

>>> print_diagnosis(MODULE_PATH_OR_PKG_FOLDER)

Once you’re familiar with the problems, you can choose to do:

>>> repair_package(PY_FILES_DIRECTORY, write_to_files=True)

This will attempt to repair the problems for you.

>>> docs = '''
... The doctest won't render correctly if it's not preceeded by a blank line:
...     >>> like_this
...
... But with a blank line before a block of doctests, it's fine
...
... >>> okay
...
...     Is also detected in indentations
...     >>> this_doctest_is_too_close_to_text
...     SOME_OUTPUT
...     >>> but_this_is_fine
...     since it's within a doctest block
...
... '''
>>>
>>>
>>> new_docs = add_newlines_before_doctests_when_missing(docs)
>>> assert new_docs == '''
... The doctest won't render correctly if it's not preceeded by a blank line:
...
...     >>> like_this
...
... But with a blank line before a block of doctests, it's fine
...
... >>> okay
...
...     Is also detected in indentations
...
...     >>> this_doctest_is_too_close_to_text
...     SOME_OUTPUT
...     >>> but_this_is_fine
...     since it's within a doctest block
...
... '''

The published_doc_diagnosis_df gets you a pandas dataframe (requires pandas to be installed!) that will tell you if given github org/repo url(s) have published documentation and if a docs folder even exists (in master branch):

>>> from epythet.tools import published_doc_diagnosis_df
>>> published_doc_diagnosis_df('https://github.com/i2mint/epythet')
                                 url                      doc_page_url  doc_page_exists  repo_has_docs_folder
0  https://github.com/i2mint/epythet  https://i2mint.github.io/epythet             True                  True
>>> published_doc_diagnosis_df([
...     'https://github.com/i2mint/epythet', 'https://github.com/myorg/myrepo',
... ])
                                 url                      doc_page_url  doc_page_exists  repo_has_docs_folder
0  https://github.com/i2mint/epythet  https://i2mint.github.io/epythet             True                  True
1    https://github.com/myorg/myrepo    https://myorg.github.io/myrepo            False                 False

Functions

print_diagnosis(src)

epythet.tools.beginning_of_doctest(string, pos=0, endpos=9223372036854775807)¶: Matches zero or more characters at the beginning of the string.

epythet.tools.blank_line(string, pos=0, endpos=9223372036854775807)¶: Matches zero or more characters at the beginning of the string.

Modules

`docstring_diagnosis`	Tools to manipulate documentation elements
`published_docs`	Elements for a tool to setup docs and check if docs are published, and if not, why.