Skip to content

PYTHON-2870 Add support for man/text/latex/etc.. docs output #708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 19, 2021

Conversation

ShaneHarvey
Copy link
Member

This PR adds support for building the docs in non-html output formats. For example man/latex/text are now supported. In order to do this I removed the mongodoc extension which doesn't add much value anyway. I also regenerated sphinx's doc/Makefile with sphinx-quickstart 3.5.4.

To build the docs in different formats:

cd doc
make man latex text html

@behackett
Copy link
Member

I think the point of mongodoc is to generate links to dochub references, which are supposed to be stable long term. Are you sure we aren't losing something by getting rid of it?

@ShaneHarvey
Copy link
Member Author

We're not loosing anything AFAICT. We're still linking to the dochub pages. The only thing mongodoc does is automatically replace this:

.. mongodoc:: rs

with this:

.. seealso:: The MongoDB documentation on: `rs <https://dochub.mongodb.org/core/rs>`_

After this change we just explicitly link to the page:

.. seealso:: The `MongoDB documentation on Replication <https://dochub.mongodb.org/core/rs>`_

Copy link
Member

@behackett behackett left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. Great. LGTM.

@kloczek
Copy link

kloczek commented Aug 19, 2021

Unsing that Makefile soes not make any sense.
All what needs to be done is correctly implement setuptools<>sphinx integration
https://www.sphinx-doc.org/en/master/usage/advanced/setuptools.html

@ShaneHarvey
Copy link
Member Author

setup.py build_sphinx also works as expected after these changes:

$ python setup.py build_sphinx -b man --build-dir build/sphinx
--
running build_sphinx
Running Sphinx v4.1.2
making output directory... done
loading intersphinx inventory from http://www.gevent.org/objects.inv...
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 79 added, 0 changed, 0 removed
reading sources... [100%] tutorial
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... pymongo.1 { atlas installation tutorial examples/index examples/aggregation examples/authentication examples/collations examples/copydb examples/custom_type examples/bulk examples/datetimes examples/geo examples/gevent examples/gridfs examples/high_availability examples/mod_wsgi examples/server_selection examples/tailable examples/tls examples/encryption examples/uuid faq compatibility-policy api/index api/bson/index api/bson/binary api/bson/code api/bson/codec_options api/bson/dbref api/bson/decimal128 api/bson/errors api/bson/int64 api/bson/json_util api/bson/max_key api/bson/min_key api/bson/objectid api/bson/raw_bson api/bson/regex api/bson/son api/bson/timestamp api/bson/tz_util api/pymongo/index api/pymongo/bulk api/pymongo/change_stream api/pymongo/client_session api/pymongo/collation api/pymongo/collection api/pymongo/command_cursor api/pymongo/cursor api/pymongo/database api/pymongo/driver_info api/pymongo/encryption api/pymongo/encryption_options api/pymongo/errors api/pymongo/mongo_client api/pymongo/monitoring api/pymongo/operations api/pymongo/pool api/pymongo/read_concern api/pymongo/read_preferences api/pymongo/results api/pymongo/server_api api/pymongo/server_description api/pymongo/topology_description api/pymongo/uri_parser api/pymongo/write_concern api/pymongo/event_loggers api/gridfs/index api/gridfs/errors api/gridfs/grid_file tools contributors changelog python3 migrate-to-pymongo4 migrate-to-pymongo3 developer/index developer/periodic_executor } done
build succeeded.
 
The manual pages are in build/sphinx/man.

@ShaneHarvey ShaneHarvey merged commit f9bfd11 into mongodb:master Aug 19, 2021
@ShaneHarvey ShaneHarvey deleted the PYTHON-2870 branch August 19, 2021 20:58
ShaneHarvey added a commit that referenced this pull request Aug 19, 2021
Regenerate sphinx makefile with sphinx-quickstart 3.5.4.
Remove problematic mongodoc sphinx extension.

(cherry picked from commit f9bfd11)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants