usage on readthedocs.org

[cjw296]

• I have searched the issues of this repo and believe that this is not a duplicate.

Issue

How can I have readthedocs.org build a project that I'm developing using poetry?
Hopefully this is just a documentation issue...

[jacebrowning]

@cjw296 Did you run into a specific error when building your site?

My mkdocs site built fine without telling readthedocs.org anything about poetry: https://datafiles.readthedocs.io

[cjw296]

How did you install your package? Doesn’t rtd only support pip (and maybe conda if you’re very lucky?)

…

On 19 Dec 2018, at 15:20, Jace Browning ***@***.***> wrote: @cjw296 Did you run into a specific error when building your site? My mkdocs site built fine without telling readthedocs.org anything about poetry: https://datafiles.readthedocs.io — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[jacebrowning]

The only setting I changed from the defaults was to select the framework for my docs:

I don't think RTD needs the rest of your dependencies.

[cjw296]

I use Sphinx, and to build correctly, the package needs to be installed.

[cjw296]

RTD issue here: readthedocs/readthedocs.org#4912
May well be fixed by pypa/pip#6106.

[GPMueller]

Aside from documentation I don't belive this is an issue of poetry, but of readthedocs.
Installing it there should not be a problem, but I was not successful running poetry there, because of missing system packages.

However, documentation on how to use RTD would be great! 👍

[ahal]

Not a super elegant solution, but you can use a requirements.txt to manually point to the packages you want autodoc to find. E.g add the following file to your repo root:

requirements.readthedocs.txt

src/my_package
src/my_other_package

Then enable requirements.readthedocs.txt in the readthedocs admin panel. That's enough to allow autodoc to find the package. You may need to add some dependencies there too.

[trim21]

Is there any way to install dev-dependencies by pip install . instead of put sphinx in extra requirements?

version: 2

python:
  version: 3.6
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

[cjw296]

I suspect this requires the "editable install support as an extension to PEP 517" mentioned in pypa/pip#6314 (comment).

[cjw296]

@finswimmer - can you explain why you've closed this?

[finswimmer]

Hello @cjw296,

sorry I could have written some words about it. I've closed this because there were nor more comments for more than a year. Furthermore it doesn't look like a poetry problem. If you disagree please explain it a bit more, why you think that is something poetry should solve. We can discuss about it of course.

fin swimmer

[cjw296]

Poetry's direction and approach seems pretty hostile to my use cases nowadays, and closing issues just because no-one's had time to bottom them out seems counterproductive. This isn't the first time I've disagreed with your approach, and I'm sorry to see @sdispater cede so much direction and control of this project to you; Poetry had plenty of potential, but the direction you're driving it doesn't work for me.

[sdispater]

@cjw296

Poetry's direction and approach seems pretty hostile to my use cases nowadays

Are you saying that we should accept and abide by your use cases, no questions asked?

The thing is that I agree with @finswimmer here: this is not an issue with Poetry but with RTD and you already pointed to an issue on the RTD repository where the discussion is more suited (readthedocs/readthedocs.org#4912).

That being said, if you feel that Poetry could do something here and you are willing to implement it, I'd happily review a PR but for now I really think this is out of our hands.

[AKuederle]

RTD does seem to allow custom shell commands with the most recent update: https://docs.readthedocs.io/en/latest/build-customization.html

I havn't tested it yet, but I assume this should allow to install dev dependencies (or in Poetry 1.2 and higher the respective dependency groups for docs)

EDIT: Here is a link to a working solution using this feature: readthedocs/readthedocs.org#4912 (comment)

[rlaphoenix]

Is there any way to install dev-dependencies by pip install . instead of put sphinx in extra requirements?

version: 2

python:
  version: 3.6
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

Do note that this will install all optional dependencies, which is really not ideal. It effectively makes specifying extra_requirements pointless, as it will just install every dependency under [tool.poetry.dependencies] anyway.

I recommend doing the solution linked by @AKuederle but add --no-dev -E docs to the end of the poetry install line under post_install.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.