0.21.0: remoed sphinx suport

[kloczek]

Is it any reason why docsconf.py has been removed?
mkdoc does not support generate man page which swill is most common U*nix documentation format.

[nandgator]

Validators is not a CLI tool (yet?), so I doubt man pages are unavoidable. On the other hand Python's help() works fine.

>>> help(validators)
 
Help on package validators:

NAME
    validators - Validate Anything!

PACKAGE CONTENTS
    _extremes
    between
    btc_address
    card
    domain
    email
    hashes
    hostname
    i18n (package)
    iban
    ip_address
    length
    mac_address
    slug
    url
    utils
    uuid

CLASSES
    builtins.Exception(builtins.BaseException)
        validators.utils.ValidationFailure
    
    class ValidationFailure(builtins.Exception)

...

[kloczek]

Wo sayid that man pages are only for CLI? 🤔
What Cli or not ha sto do witj generated documentation format?

Here is man page documetation for prev ersion

PYTHON-VALIDATORS(3)                                                                   validators                                                                   PYTHON-VALIDATORS(3)

NAME
       python-validators - validators Python Module Documentation

       Python Data Validation for Humans™.

       Python  has  all kinds of validation tools, but every one of them requires defining a schema. I wanted to create a simple validation library where validating a simple value does
       not require defining a form or a schema.  Apparently some other guys have felt the same way.

       Often I've had for example a case where I just wanted to check if given string is an email. With validators this use case becomes as easy as:

          >>> import validators

          >>> validators.email('someone@example.com')
          True

       You can install validators using pip:

          pip install validators

       Currently validators supports python versions 2.7, 3.3, 3.4, 3.5, 3.6, 3.7 and PyPy.

       Each validator in validators is a simple function that takes the value to validate and possibly some additional key-value arguments. Each function returns True  when  validation
       succeeds and ValidationFailure object when validation fails.

       ValidationFailure class implements __bool__ method so you can easily check if validation failed:

          >>> if not validators.email('some_bogus_email@@@'):
          ...     # Do something here
          ...     pass

       ValidationFailure object also holds all the arguments passed to original function:

          >>> result = validators.between(3, min=5)
          >>> result.value
          3
          >>> result.min
          5

BETWEEN
       validators.between.between(value, min=None, max=None)
              Validate that a number is between minimum and/or maximum value.

              This will work with any comparable type, such as floats, decimals and dates not just integers.

              This validator is originally based on WTForms NumberRange validator.

              Examples:

                 >>> from datetime import datetime

                 >>> between(5, min=2)
                 True

                 >>> between(13.2, min=13, max=14)
                 True

                 >>> between(500, max=400)
                 ValidationFailure(func=between, args=...)

                 >>> between(
                 ...     datetime(2000, 11, 11),
                 ...     min=datetime(1999, 11, 11)
                 ... )
                 True

              Parameters

                     • min -- The minimum required value of the number. If not provided, minimum value will not be checked.

                     • max -- The maximum value of the number. If not provided, maximum value will not be checked.

              New in version 0.2.

BTC_ADDRESS
       validators.btc_address.btc_address(value)
              Return whether or not given value is a valid bitcoin address.

              If the value is valid bitcoin address this function returns True, otherwise ValidationFailure.

              Full validation is implemented for P2PKH and P2SH addresses.  For segwit addresses a regexp is used to provide a reasonable estimate on whether the address is valid.

              Examples:

                 >>> btc_address('3Cwgr2g7vsi1bXDUkpEnVoRLA9w4FZfC69')
                 True

              Parameters
                     value -- Bitcoin address string to validate

DOMAIN
       validators.domain.domain(value)
              Return whether or not given value is a valid domain.

              If the value is valid domain name this function returns True, otherwise ValidationFailure.

              Examples:

                 >>> domain('example.com')
                 True

                 >>> domain('example.com/')
                 ValidationFailure(func=domain, ...)

              Supports IDN domains as well:

                 >>> domain('xn----gtbspbbmkef.xn--p1ai')
                 True

              New in version 0.9.

              Changed in version 0.10: Added support for internationalized domain name (IDN) validation.

              Parameters
                     value -- domain string to validate

EMAIL
       validators.email.email(value, whitelist=None)
              Validate an email address.

              This validator is based on Django's email validator. Returns True on success and ValidationFailure when validation fails.

              Examples:

                 >>> email('someone@example.com')
                 True

                 >>> email('bogus@@')
                 ValidationFailure(func=email, ...)

              New in version 0.1.

              Parameters

                     • value -- value to validate

                     • whitelist -- domain names to whitelist

              Copyright

                     c. Django Software Foundation and individual contributors.

              License
                     BSD

IBAN
       validators.iban.iban(value)
              Return whether or not given value is a valid IBAN code.

              If the value is a valid IBAN this function returns True, otherwise ValidationFailure.

              Examples:

                 >>> iban('DE29100500001061045672')
                 True

                 >>> iban('123456')
                 ValidationFailure(func=iban, ...)

              New in version 0.8.

              Parameters
                     value -- IBAN string to validate

IPV4
       validators.ip_address.ipv4(value)
              Return whether a given value is a valid IP version 4 address.

              This validator is based on WTForms IPAddress validator

              Examples:

                 >>> ipv4('123.0.0.7')
                 True

                 >>> ipv4('900.80.70.11')
                 ValidationFailure(func=ipv4, args={'value': '900.80.70.11'})

              New in version 0.2.

              Parameters
                     value -- IP address string to validate

IPV6
       validators.ip_address.ipv6(value)
              Return whether a given value is a valid IP version 6 address (including IPv4-mapped IPv6 addresses).

              This validator is based on WTForms IPAddress validator.

              Examples:

                 >>> ipv6('abcd:ef::42:1')
                 True

                 >>> ipv6('::ffff:192.0.2.128')
                 True

                 >>> ipv6('::192.0.2.128')
                 True

                 >>> ipv6('abc.0.0.1')
                 ValidationFailure(func=ipv6, args={'value': 'abc.0.0.1'})

              New in version 0.2.

              Parameters
                     value -- IP address string to validate

LENGTH
       validators.length.length(value, min=None, max=None)
              Return whether or not the length of given string is within a specified range.

              Examples:

                 >>> length('something', min=2)
                 True

                 >>> length('something', min=9, max=9)
                 True

                 >>> length('something', max=5)
                 ValidationFailure(func=length, ...)

              Parameters

                     • value -- The string to validate.

                     • min -- The minimum required length of the string. If not provided, minimum length will not be checked.

                     • max -- The maximum length of the string. If not provided, maximum length will not be checked.

              New in version 0.2.

MAC_ADDRESS
       validators.mac_address.mac_address(value)
              Return whether or not given value is a valid MAC address.

              If the value is valid MAC address this function returns True, otherwise ValidationFailure.

              This validator is based on WTForms MacAddress validator.

              Examples:

                 >>> mac_address('01:23:45:67:ab:CD')
                 True

                 >>> mac_address('00:00:00:00:00')
                 ValidationFailure(func=mac_address, args={'value': '00:00:00:00:00'})

              New in version 0.2.

              Parameters
                     value -- Mac address string to validate

MD5
       validators.hashes.md5(value)
              Return whether or not given value is a valid MD5 hash.

              Examples:

                 >>> md5('d41d8cd98f00b204e9800998ecf8427e')
                 True

                 >>> md5('900zz11')
                 ValidationFailure(func=md5, args={'value': '900zz11'})

              Parameters
                     value -- MD5 string to validate

SHA1
       validators.hashes.sha1(value)
              Return whether or not given value is a valid SHA1 hash.

              Examples:

                 >>> sha1('da39a3ee5e6b4b0d3255bfef95601890afd80709')
                 True

                 >>> sha1('900zz11')
                 ValidationFailure(func=sha1, args={'value': '900zz11'})

              Parameters
                     value -- SHA1 string to validate

SHA224
       validators.hashes.sha224(value)
              Return whether or not given value is a valid SHA224 hash.

              Examples:

                 >>> sha224('d14a028c2a3a2bc9476102bb288234c415a2b01f828ea62ac5b3e42f')
                 True

                 >>> sha224('900zz11')
                 ValidationFailure(func=sha224, args={'value': '900zz11'})

              Parameters
                     value -- SHA224 string to validate

SHA256
       validators.hashes.sha256(value)
              Return whether or not given value is a valid SHA256 hash.

              Examples:

                 >>> sha256(
                 ...     'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b'
                 ...     '855'
                 ... )
                 True

                 >>> sha256('900zz11')
                 ValidationFailure(func=sha256, args={'value': '900zz11'})

              Parameters
                     value -- SHA256 string to validate

SHA512
       validators.hashes.sha512(value)
              Return whether or not given value is a valid SHA512 hash.

              Examples:

                 >>> sha512(
                 ...     'cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce'
                 ...     '9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af9'
                 ...     '27da3e'
                 ... )
                 True

                 >>> sha512('900zz11')
                 ValidationFailure(func=sha512, args={'value': '900zz11'})

              Parameters
                     value -- SHA512 string to validate

SLUG
       validators.slug.slug(value)
              Validate whether or not given value is valid slug.

              Valid slug can contain only alphanumeric characters, hyphens and underscores.

              Examples:

                 >>> slug('my.slug')
                 ValidationFailure(func=slug, args={'value': 'my.slug'})

                 >>> slug('my-slug-2134')
                 True

              New in version 0.6.

              Parameters
                     value -- value to validate

TRUTHY
       validators.truthy.truthy(value)
              Validate that given value is not a falsey value.

              This validator is based on WTForms DataRequired validator.

              Examples:

                 >>> truthy(1)
                 True

                 >>> truthy('someone')
                 True

                 >>> truthy(0)
                 ValidationFailure(func=truthy, args={'value': 0})

                 >>> truthy('    ')
                 ValidationFailure(func=truthy, args={'value': '    '})

                 >>> truthy(False)
                 ValidationFailure(func=truthy, args={'value': False})

                 >>> truthy(None)
                 ValidationFailure(func=truthy, args={'value': None})

              New in version 0.2.

URL
       validators.url.url(value, public=False)
              Return whether or not given value is a valid URL.

              If the value is valid URL this function returns True, otherwise ValidationFailure.

              This validator is based on the wonderful URL validator of dperini.

              Examples:

                 >>> url('http://foobar.dk')
                 True

                 >>> url('ftp://foobar.dk')
                 True

                 >>> url('http://10.0.0.1')
                 True

                 >>> url('http://foobar.d')
                 ValidationFailure(func=url, ...)

                 >>> url('http://10.0.0.1', public=True)
                 ValidationFailure(func=url, ...)

              New in version 0.2.

              Changed in version 0.10.2: Added support for various exotic URLs and fixed various false positives.

              Changed in version 0.10.3: Added public parameter.

              Changed in version 0.11.0: Made the regular expression this function uses case insensitive.

              Changed in version 0.11.3: Added support for URLs containing localhost

              Parameters

                     • value -- URL address string to validate

                     • public -- (default=False) Set True to only allow a public IP address

UUID
       validators.uuid.uuid(value)
              Return whether or not given value is a valid UUID.

              If the value is valid UUID this function returns True, otherwise ValidationFailure.

              This validator is based on WTForms UUID validator.

              Examples:

                 >>> uuid('2bc1c94f-0deb-43e9-92a1-4775189ec9f8')
                 True

                 >>> uuid('2bc1c94f 0deb-43e9-92a1-4775189ec9f8')
                 ValidationFailure(func=uuid, ...)

              New in version 0.2.

              Parameters
                     value -- UUID value to validate

SPANISH
   es_doi
       validators.i18n.es.es_doi(doi)
              Validate a Spanish DOI.

              A DOI in spain is all NIF / CIF / NIE / DNI -- a digital ID. For more information see wikipedia.org/doi.

              This validator is based on generadordni.es.

              Examples:

                 >>> es_doi('X0095892M')
                 True

                 >>> es_doi('X0095892X')
                 ValidationFailure(func=es_doi, args=...)

              New in version 0.13.0.

              Parameters
                     doi -- DOI to validate

   es_nif
       validators.i18n.es.es_nif(doi)
              Validate a Spanish NIF.

              Each  entity,  be it person or company in Spain has a distinct NIF. Since we've designated CIF to be a company NIF, this NIF is only for person.  For more information see
              wikipedia.org/nif.

              This validator is based on generadordni.es.

              Examples:

                 >>> es_nif('26643189N')
                 True

                 >>> es_nif('26643189X')
                 ValidationFailure(func=es_nif, args=...)

              New in version 0.13.0.

              Parameters
                     doi -- DOI to validate

   es_nie
       validators.i18n.es.es_nie(doi)
              Validate a Spanish NIE.

              The NIE is a tax identification number in Spain, known in Spanish as the NIE, or  more  formally  the  Número  de  identidad  de  extranjero.  For  more  information  see
              wikipedia.org/nie.

              This validator is based on generadordni.es.

              Examples:

                 >>> es_nie('X0095892M')
                 True

                 >>> es_nie('X0095892X')
                 ValidationFailure(func=es_nie, args=...)

              New in version 0.13.0.

              Parameters
                     doi -- DOI to validate

   es_cif
       validators.i18n.es.es_cif(doi)
              Validate a Spanish CIF.

              Each company in Spain prior to 2008 had a distinct CIF and has been discontinued. For more information see wikipedia.org/cif.

              The  new  replacement  is to use NIF for absolutely everything. The issue is that there are "types" of NIFs now: company, person[citizen vs recident] all distinguished by
              the first character of the DOI. For this reason we will continue to call CIF NIFs that are used for companies.

              This validator is based on generadordni.es.

              Examples:

                 >>> es_cif('B25162520')
                 True

                 >>> es_cif('B25162529')
                 ValidationFailure(func=es_cif, args=...)

              New in version 0.13.0.

              Parameters
                     doi -- DOI to validate

FINNISH
   fi_business_id
       validators.i18n.fi.fi_business_id(business_id)
              Validate a Finnish Business ID.

              Each company in Finland has a distinct business id. For more information see Finnish Trade Register

              Examples:

                 >>> fi_business_id('0112038-9')  # Fast Monkeys Ltd
                 True

                 >>> fi_business_id('1234567-8')  # Bogus ID
                 ValidationFailure(func=fi_business_id, ...)

              New in version 0.4.

              Changed in version 0.5: Method renamed from finnish_business_id to fi_business_id

              Parameters
                     business_id -- business_id to validate

   fi_ssn
       validators.i18n.fi.fi_ssn(ssn, allow_temporal_ssn=True)
              Validate a Finnish Social Security Number.

              This validator is based on django-localflavor-fi.

              Examples:

                 >>> fi_ssn('010101-0101')
                 True

                 >>> fi_ssn('101010-0102')
                 ValidationFailure(func=fi_ssn, args=...)

              New in version 0.5.

              Parameters

                     • ssn -- Social Security Number to validate

                     • allow_temporal_ssn -- Whether to accept temporal SSN numbers. Temporal SSN numbers are the ones where the serial is in the range [900-999]. By  default  temporal
                       SSN numbers are valid.

VALIDATOR
       class validators.utils.ValidationFailure(func, args)

       validators.utils.validator(func, *args, **kwargs)
              A decorator that makes given function validator.

              Whenever the given function is called and returns False value this decorator returns ValidationFailure object.

              Example:

                 >>> @validator
                 ... def even(value):
                 ...     return not (value % 2)

                 >>> even(4)
                 True

                 >>> even(5)
                 ValidationFailure(func=even, args={'value': 5})

              Parameters

                     • func -- function to decorate

                     • args -- positional function arguments

                     • kwargs -- key value function arguments

AUTHOR
       Konsta Vesterinen

COPYRIGHT
       2013-2014, Konsta Vesterinen

0.20.0                                                                                Jan 28, 2023                                                                  PYTHON-VALIDATORS(3)

[nandgator]

I have not qualms in adding Sphinx, except that it feels clunky and redundant.

Wo sayid that man pages are only for CLI?

Help me understand, how do you use man pages, of a library (a non-CLI tool)?

(For reference of course, but you can refer online docs and offline with help(validators)) how else do you use the documentation?

I see there's a Debian policy to have man pages for each package.

[kloczek]

I have not qualms in adding Sphinx, except that it feels clunky and redundant.

Issue is that documentation include is packaged mdule is not only for you.

Help me understand, how do you use man pages, of a library (a non-CLI tool)?

Man command provides acess to the DOCUMENTATION.
From man1(1):

       The table below shows the section numbers of the manual followed by the types of pages they contain.

       1   Executable programs or shell commands
       2   System calls (functions provided by the kernel)
       3   Library calls (functions within program libraries)
       4   Special files (usually found in /dev)
       5   File formats and conventions, e.g. /etc/passwd
       6   Games
       7   Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7), man-pages(7)
       8   System administration commands (usually only for root)
       9   Kernel routines [Non standard]

       A manual page consists of several sections.

On packagin modules I'm packaging python modules documentation as lvl 3 man pages and if you will look on copied generated man page for your module that man page provides exactly what shoud bi provided on that level.

Reall .. pleas restore conf,py to allow generate documentation for your module as man page.

[nandgator]

Issue is that documentation include is packaged mdule is not only for you.

Agreed, that's why I've taken extra steps to generate markdown documentation for offline package distribution.

validators/build.py

Line 13 in 68227f2

generate_documentation(project_dir, discard_refs=False)

validators/.github/workflows/build.yml

Lines 37 to 41 in 68227f2

	# build package
	- name: Build package
	run: |
	source .venv/bin/activate
	python build.py

Man command provides acess to the DOCUMENTATION.

I understand what man-pages do.

On packagin modules I'm packaging python modules documentation as lvl 3 man pages.

Can you please elaborate?

---

By the way you can still generate man-formatted documentation using podc3 and pandoc.

$ pdoc --html --output-dir html-docs validators
$ pandoc -s -t man html-docs/validators/index.html -o validators.1
$ man ./validators.1

validators API documentation()                                     validators API documentation()

Package validators
       Validate Anything!  Expand source code

              """Validate Anything!"""
              # -*- coding: utf-8 -*-

              # isort: skip_file

              # The following imports are sorted alphabetically, manually.
              # Each line is grouped based first or type, then sorted alphabetically.
              # This is for the reference documentation.

              # local
              from .between import between
              from .btc_address import btc_address
              from .card import amex, card_number, diners, discover, jcb, mastercard, unionpay, visa

[kloczek]

By the way you can still generate man-formatted documentation using podc3 and pandoc.

Please try to compare your result with what I've copied here.
Again .. mkdoc does not offer anything else than html and mkdoc maintainer do not see any needs to provide sometning else.
Sphinx ATM provides possibility natively rendering to 16 formats.

Maybe this will convince you.

[tkloczko@pers-jacek SPECS]$ grep %pyproject_wheel *spec -l | wc -l
1133
[tkloczko@pers-jacek SPECS]$ grep %pyproject_wheel *spec -l | xargs grep %sphinx_build_man -l | wc -l
540

So above shows that I have +1.1k rpm spec files amongst which almost half provides documentation which is possible to render using sphinx.
Example commandline output in devel env which I'm using now working on another package with python module:

[tkloczko@pers-jacek SPECS]$ man python-<tab><tab>
python-aiosqlite                 python-jinja2                    python-prompt_toolkit
python-anyiodoc                  python-jsonpointer               python-psutil
python-argon2-cffi               python-jsonschema                python-ptyprocess
python-arrow                     python-jupyter-client            python-pygments
python-asttokens                 python-jupyter-core              python-pyparsing
python-babel                     python-jupyter-events            python-pyproject-hooks
python-backcall                  python-jupyter-server            python-pyrsistent
python-beautifulsoup             python-jupyter-server-fileid     python-pytest
python-bleach                    python-jupyter-server-terminals  python-requests
python-build                     python-jupyter-server-ydoc       python-setuptools
python-cffi                      python-jupyter-ydoc              python-six
python-charset-normalizer        python-jupyterlab-server         python-sniffio
python-contourpy                 python-jupyternotebook           python-terminado
python-cycler                    python-kiwi                      python-tinycss2
python-dateutil                  python-markupsafe                python-traitlets
python-decorator                 python-metaextract               python-urllib3
python-fastjsonschema            python-mistune                   python-wcwidth
python-fonttools                 python-nbclient                  python-webcolors
python-fqdn                      python-nbconvert                 python-webencodings
python-html5lib                  python-nbformat                  python-websocket-client
python-importlib-metadata        python-olefile                   python-wheel
python-importlib_resources       python-parso                     python-y-py
python-ipykernel                 python-pillow                    python-zipp
python-ipython                   python-platformdirs              python-zmq
python-jedi                      python-pluggy

html is nice however if you need to find someting quckly with man page you can find that still way faster than using web page using web browser.

[kloczek]

Thank you 👍