sphinx-rtd-theme should be a dev-dependency

[SamEdwardes]

To make readthedocs work I had to make sphinx-rtd-theme a dependency.

pydatafaker/pyproject.toml

Line 12 in 74aa03d

sphinx-rtd-theme = "^0.5.0" # should be a dev requirement, but for readthedocs to build must by a dependency

It is not actually required, but for some reason the docs did not build when I moved it to:

[tool.poetry.dev-dependencies]
sphinx-rtd-theme = "^0.5.0" 

It would be ideal to find a way to make the docs build with sphinx-rtd-theme = "^0.5.0" in [tool.poetry.dev-dependencies].

Error message from readthedocs:

Running Sphinx v1.8.5
loading translations [en]... done
making output directory...
[autosummary] generating autosummary for: api_reference.rst, contributing.rst, index.rst, usage.rst
[autosummary] generating autosummary for: /home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/checkouts/business_and_docs/docs/source/generated/pydatafaker.business.create_business.rst, /home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/checkouts/business_and_docs/docs/source/generated/pydatafaker.business.create_employee_table.rst, /home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/checkouts/business_and_docs/docs/source/generated/pydatafaker.business.create_invoice_table.rst, /home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/checkouts/business_and_docs/docs/source/generated/pydatafaker.business.create_po_table.rst, /home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/checkouts/business_and_docs/docs/source/generated/pydatafaker.business.create_vendor_table.rst, /home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/checkouts/business_and_docs/docs/source/generated/pydatafaker.business.rst
building [mo]: targets for 0 po files that are out of date
building [readthedocs]: targets for 4 source files that are out of date
updating environment: 10 added, 0 changed, 0 removed
reading sources... [ 10%] api_reference
reading sources... [ 20%] contributing
reading sources... [ 30%] generated/pydatafaker.business
reading sources... [ 40%] generated/pydatafaker.business.create_business
reading sources... [ 50%] generated/pydatafaker.business.create_employee_table
reading sources... [ 60%] generated/pydatafaker.business.create_invoice_table
reading sources... [ 70%] generated/pydatafaker.business.create_po_table
reading sources... [ 80%] generated/pydatafaker.business.create_vendor_table
reading sources... [ 90%] index
reading sources... [100%] usage


Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/envs/business_and_docs/lib/python3.7/site-packages/sphinx/cmd/build.py", line 304, in build_main
    app.build(args.force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/envs/business_and_docs/lib/python3.7/site-packages/sphinx/application.py", line 341, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/envs/business_and_docs/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 347, in build_update
    len(to_build))
  File "/home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/envs/business_and_docs/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 360, in build
    updated_docnames = set(self.read())
  File "/home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/envs/business_and_docs/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 472, in read
    self.env.doc2path(self.config.master_doc))
sphinx.errors.SphinxError: master file /home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/checkouts/business_and_docs/docs/source/contents.rst not found

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/pydatafaker/checkouts/business_and_docs/docs/source/contents.rst not found

[SamEdwardes]

Hey @TomasBeuzen, I am sure you are super busy with school starting... but wondering if you had any ideas on fixes? I am developing this Python package using poetry. I am trying to publish to readthedocs.

When I include my desired sphinx theme as a dependency the build works. But this is not desired, as when the user pip installs the package it downloads packages that are not really required.

# pyproject.toml
[tool.poetry.dependencies]
python = "^3.7"
pandas = "^1.1.1"
faker = "^4.1.2"
sphinx-rtd-theme = "^0.5.0" # should be a dev requirement, but for readthedocs to build must by a dependency

When I set up correctly, for some reason the build fails (not sure if this link will work for you, but it is too failed build.

[tool.poetry.dependencies]
python = "^3.7"
pandas = "^1.1.1"
faker = "^4.1.2"

[tool.poetry.dev-dependencies]
pytest = "^6.0.1"
black = {version = "^20.8b1", allow-prereleases = true}
sphinx = "^3.2.1"
sphinxcontrib-napoleon = "^0.7"
sphinx-rtd-theme = "^0.5.0" # should be a dev requirement, but for readthedocs to build must by a dependency
pytest-cov = "^2.10.1"

I have the .readthedocs.yml from your cookiecutter project, but it doesn't seem to do the trick.

# .readthedocs.yml
# https://github.com/UBC-MDS/cookiecutter-ubc-mds/blob/master/%7B%7Bcookiecutter.project_slug%7D%7D/.readthedocs.yml

build:
    image: latest
python:
    version: 3.7
    pip_install: true
    extra_requirements:
        - docs

Similar issues on GitHub include:

• usage on readthedocs.org python-poetry/poetry#754
• Support Poetry readthedocs/readthedocs.org#4912
• Unable to build docs with poetry readthedocs/readthedocs.org#6151

[TomasBeuzen]

@SamEdwardes - just letting you know I've seen this but don't have any ideas off the top of my head. I'll take a look at this if I get a chance next week.

As an aside... I must admit I'm not a huge fan of RTD anymore, I mostly use Jupyter Book now and am interested in checking out https://docusaurus.io/en/ (both of which I plan on documenting in https://py-pkgs.org/)

[SamEdwardes]

Thanks for the feedback Tom. I will check out those other alternatives as well. I am open to using sites other than RTD.

[SamEdwardes]

Just in case it can help anyone in the future (maybe @TomasBeuzen), I found a hacky way to work around this:

• I include sphinx-rtd-theme as a dev dependency, as it should be
• I created a new branch off of the master called docs
• every time I merge a PR with master, I trigger a github action (publish_docs.yml) that:
  • merges master into docs
  • moves sphinx-rtd-theme in the docs branch to a required dependency
• read the docs is set up to generate docs from the docs branch

This approach works, and is now low effort because it is automated. But it was tricky to set up.