Build documentation using setuptools build_sphinx

[kloczek]

• I've gone though the User Guide and the API reference
• I've searched for previous similar issues and didn't find any solution

Describe the bug
setuptools build_sphinx target fails because it cannot find awscli module.
The same targets are working without problems wit boto3 and botocore.

SDK version number
1.19.85

Platform/OS/Hardware/Device
What are you running the cli on?

Linux/x86_64

To Reproduce (observed behavior)
Run command in source code root:

$ /usr/bin/python3 setup.py build_sphinx -b man

Expected behavior
All man pages declared in doc/source/copy.py shoul be generated

Logs/output
Get full traceback and error logs by adding --debug to the command.

+ /usr/bin/python3 setup.py build_sphinx -b man
running build_sphinx
Running Sphinx v4.0.2
Traceback (most recent call last):
  File "/home/tkloczko/rpmbuild/BUILD/aws-cli-1.19.85/doc/source/htmlgen", line 6, in <module>
    import awscli.clidriver
ModuleNotFoundError: No module named 'awscli'

Additional context
N/A

[kdaily]

Hi @kloczek,

Are you trying to build the documentation? If so, the instructions for that are here:

https://github.com/aws/aws-cli/blob/develop/doc/README.rst

To build the man pages, you can run the make man command:

https://github.com/aws/aws-cli/blob/develop/doc/Makefile#L121-L124

[github-actions]

Greetings! It looks like this issue hasn’t been active in longer than a week. We encourage you to check if this is still an issue in the latest release. Because it has been longer than a week since the last update on this, and in the absence of more information, we will be closing this issue soon. If you find that this is still a problem, please feel free to provide a comment or add an upvote to prevent automatic closure, or if the issue is already closed, please feel free to open a new one.

[kloczek]

Q: why it is not possible to hook that under setuptools build_sphins command?

Is it rocjet schence to use just standard way of generating sphinx documentation
If it would be correwcrly implemented that makefile can be removed (KISS principle).
Please instead defining DIY build processes just stick with what setuptools offer.

[kdaily]

Hi @kloczek,
Thanks for your feedback. The pattern used here is common - many other high profile Python packages work the same way. For example:

• Flask: https://github.com/pallets/flask/tree/main/docs
• scikit-learn: https://scikit-learn.org/dev/developers/contributing.html#documentation (docs build guide here)
• Black: https://github.com/psf/black

Providing documentation builds this way would also require taking sphinx as a dependency of the package rather than in separate dependencies specific for building documentation. The docs build is also customized to generate documentation dynamically based on API models as part of the underlying Python SDK, botocore.

Can you describe your specific use cases to being able to build documentation this way or why the documented method is not sufficent?

[github-actions]

Greetings! It looks like this issue hasn’t been active in longer than a week. We encourage you to check if this is still an issue in the latest release. Because it has been longer than a week since the last update on this, and in the absence of more information, we will be closing this issue soon. If you find that this is still a problem, please feel free to provide a comment or add an upvote to prevent automatic closure, or if the issue is already closed, please feel free to open a new one.

[kloczek]

Can you describe your specific use cases to being able to build documentation this way or why the documented method is not sufficent?

I'm completing my rpm packages build procedures and in my packages standard form of delivery python modules documentation is man pages roff format.
Almost half of my ~550 python modules packages have documentation in such form.
Result is pretty handy ..

[tkloczko@barrel SRPMS]$ man python-
Display all 219 possibilities? (y or n)
python-amqp                           python-greenlet                       python-parver                         python-sniffio
python-anytree                        python-h2                             python-paste                          python-sphinxcontrib-asyncio
python-argcomplete                    python-hacking                        python-path                           python-sphinxcontrib-autoprogram
python-arrow                          python-httplib2                       python-pillow                         python-sphinxcontrib-bibtex
python-"asgi                          python-hyperframe                     python-pluggy                         python-sphinxcontrib-httpdomain
python-aspectlib                      python-hyperlink                      python-polib                          python-sphinxcontrib-programoutput
python-astor                          python-hypothesis                     python-prb                            python-sphinxcopybutton
python-astroid                        python-ifaddr                         python-priority                       python-sphinxext-opengraph
python-async_generator                python-importlib-metadata             python-productmd-compose              python-sphinx-inline-tabs
python-atomicwrites                   python-inflect                        python-productmd-composeinfo          python-sphinx-removed-in
python-attrs                          python-ipykernel                      python-productmd-discinfo             python-sphinx_rtd_theme
python-augeas                         python-itsdangerous                   python-productmd-images               python-sphinx-tabs
python-autodocsumm                    python-jaraco-classes                 python-productmd-rpms                 python-sphinx-typlog-theme
python-babel                          python-jaraco-collections             python-productmd-terminology          python-sphobjinv
python-backcall                       python-jaraco-envs                    python-productmd-treeinfo             python-sqlparse
python-benchmark                      python-jaraco-functools               python-prompt_toolkit                 python-stdlib-list
python-betamax                        python-jaraco.itertools               python-ptyprocess                     python-stem
python-billiard                       python-jaraco-packaging               python-purl                           python-sure
python-bleach                         python-jaraco-path                    python-py                             python-sybil
python-blinker                        python-jaraco-text                    python-pyasn1                         python-systemd
python-boto3                          python-jedi                           python-pybtex-docutils                python-terminado
python-botocore                       python-Jinja                          python-pycodestyle                    python-testpath
python-bottle                         python-jinja2_pluralize               python-pyfakefs                       python-testrepository
python-breathe                        python-jmespath                       python-pyftpdlib                      python-testtools
python-build                          python-jupyter_client                 python-pygal                          python-tidy
python-cachetools                     python-jupyter_core                   python-pygments                       python-tinycss2
python-case                           python-jupytext                       python-pyhamcrest                     python-tornado
python-cffi                           python-kiwi                           python-pylama                         python-traitlets
python-characteristic                 python-kombu                          python-pylint                         python-trio
python-chardet                        python-lark                           python-pymeeus                        python-trustme
python-click                          python-latexcodec                     python-pynacl                         python-twisted
python-click-log                      python-lazy-object-proxy              python-pyopenssl                      python-uritemplate
python-contextlib2                    python-libevdev                       python-pyrad                          python-urllib3
python-convertdate                    python-linkify-it-py                  python-pyrsistent                     python-validators
python-coveragepy                     python-lockfile                       python-pyscss                         python-vine
python-cppy                           python-lxml                           python-pytest                         python-waitress
python-cssselect2                     python-mako                           python-pytest-checkdocs               python-wcwidth
python-dateutil                       python-markupsafe                     python-pytest-cov                     python-webcolors
python-dictdiffer                     python-mdit-py-plugins                python-pytest-regressions             python-webencodings
python-dpkt                           python-mistune                        python-pytest-runner                  python-webob
python-dulwich                        python-more-itertools                 python-python-sphinx-contribspelling  python-websocket-client
python-elementpath                    python-msgpack                        python-pyudev                         python-websockets
python-evdev                          python-multidict                      python-pyxattr                        python-webtest
python-execnet                        python-mypy                           python-pyxdg                          python-werkzeug
python-faker                          python-myst-parser                    python-rdflib                         python-wheel
python-fields                         python-nbclient                       python-requests-mock                  python-wrapt
python-flake8                         python-nbformat                       python-requests_toolbelt              python-WSGIProxy2
python-flask                          python-netaddr                        python-rsa                            python-wsproto
python-flask-sqlalchemy               python-nose2                          python-rst.linker                     python-xmlschema
python-flit                           python-notebook                       python-scons                          python-yamlloader
python-fonttools                      python-olefile                        python-scripttest                     python-yarl
python-gcovr                          python-openstackdocstheme             python-semantic-version               python-zeroconf
python-gidocgen                       python-outcome                        python-service-identity               python-zipp
python-gitdb                          python-paramiko                       python-smartypants                    python-zope-event
python-GitPython.tex                  python-parso                          python-smmap.tex

There is no any problems with that procedure in case of those modules which have been mentioned like flask, b;ack nbut as well boto3 or botocore. All above man pages have been generated using setuptools build_sphinx command.

[kdaily]

Hi @kloczek,

Thanks for those details. I'll mark this as a feature request to provide this functionality and see if there is further demand for it. The inclusion of Sphinx as a dependency is a pretty big blocker though.

[github-actions]

Greetings! It looks like this issue hasn’t been active in longer than one year. We encourage you to check if this is still an issue in the latest release. In the absence of more information, we will be closing this issue soon. If you find that this is still a problem, please feel free to provide a comment or upvote with a reaction on the initial post to prevent automatic closure. If the issue is already closed, please feel free to open a new one.

[kloczek]

OK will try to recheck that.
Will back soon ..
Thx.

[kloczek]

This ticket is outdated.
Closing.

[github-actions]

This issue is now closed. Comments on closed issues are hard for our team to see.
If you need more assistance, please open a new issue that references this one.