Documentation update

[SilvestriStefano]

Hello, Following from a fix for issue #175 I updated most docstrings to remove the annoying Sphinx warnings (there were almost 700). Most of the warnings were due to the bad types declared in the docstrings: string instead of str, boolean instead of bool, etc.. Some warnings were about extra indentations or bad reference to methods/functions/attributes. I did have to suppress some of the warnings because I could not find a solution. I used the following option in conf.py

# Suppress warnings 'py:class reference target not found: <type>'
nitpicky = True
nitpick_ignore = [
    ('py:class','optional'),
    ('py:class','json.encoder.JSONEncoder'), # I don't understand why it can't find it
    ('py:class','Response'),
    ('py:class','Request'),
    ('py:class','_io.BytesIO'),
    ('py:class','sasctl.utils.pymas.ds2.Ds2Variable'), # not sure what is wrong 
    ('py:class','sasctl._services.service.Service') # should the Service class be documented?
]

As you can read from the last comment, there is no documentation page for the Service class, so that is the reason for the warning. For the others I am stumped:

• Commenting out the ('py:class', 'Request') you get 32 warnings simlar to this one

/py-sasctl/src/sasctl/core.py:docstring of sasctl.core.Session.delete:3: WARNING: py:class reference target not found: Request

• Similarly, commenting out the ('py:class', 'Response') you get 12 warnings simlar to this one

/py-sasctl/src/sasctl/core.py:docstring of sasctl.core.Session.delete:1: WARNING: py:class reference target not found: Response

• The _io.BytesIO warning is due to the following line of code https://github.com/sassoftware/python-sasctl/blob/5e8d8fd0be588d45dfacb9038abef4ae4e7b25c1/src/sasctl/pzmm/zip_model.py#L50
• The JSONEncoder warning is due to the following line of code https://github.com/sassoftware/python-sasctl/blob/5e8d8fd0be588d45dfacb9038abef4ae4e7b25c1/src/sasctl/pzmm/write_json_files.py#L31

At the moment the only warnings remaining are the following:

/py-sasctl/doc/index.rst:127: WARNING: TODO entry found: Add info for SERVER_NAME env var
/py-sasctl/doc/index.rst:401: WARNING: TODO entry found: feature requests / bug reports
/py-sasctl/doc/index.rst:402: WARNING: TODO entry found: review pull requests
/py-sasctl/doc/index.rst:403: WARNING: TODO entry found: triage issues
/py-sasctl/src/sasctl/utils/pymas/core.py:docstring of sasctl.utils.pymas.core.build_wrapper_function:28: WARNING: Inline interpreted text or phrase reference start-string without end-string.

/py-sasctl/doc/index.rst:495: WARNING: py:mod reference target not found: tox
/py-sasctl/doc/index.rst:503: WARNING: py:mod reference target not found: flake8

I don't understand the last two given that the intersphinx links are correct.

Signed-off-by: Stefano Silvestri [email protected]

[smlindauer]

Thanks for taking a stab at this @SilvestriStefano! Everything looks good on my end as far as review goes. I am not sure what to do about the last two warnings in regard to the intersphinx links either, but am not too worried about it if the documentation is properly showing up.

I am going to ask if @jlwalke2 can take a look as he wrote most of the sphinx documentation originally.

[jlwalke2]

Stefano, I'm sorry this languished for so long before I noticed it, but sincere thank you for contributing!!

[SilvestriStefano]

No worries! I'm glad I could help. 🙂