[Feature] --bootstrap should detect existing poetry config

[melMass]

Hi,

Sorry If I'm dumb, but I don't find the quickstart to give enough information, like from where are you supposed to issue the command, your python project root? I'm using poetry and running pydoc-markdown --bootstrap mkdocs from the root returns error: file already exists: 'pyproject.toml', will it create a subfolder, things like that. I'm pretty sure I will find the solution to all of this after playing with it a bit, but I guess I'm not the only one wondering those and it could be streamlined in the quickstart doc

Thanks for PyDoc ❤️

Close at will

[melMass]

I'm still struggling to understand how it works. I created a doc folder in the root of my project, cd to it, and run

pydoc-markdown --bootstrap mkdocs -I .. 
> error: --bootstrap must be used as a sole argument
pydoc-markdown --bootstrap mkdocs
> created pydoc-markdown.yml
pydoc-markdown --server --open -I .. 
> error: renderer 'MarkdownRenderer' cannot be used with --server

[melMass]

Oh ok, it supports reading configuration from a pyproject.toml file (that's a great feature!) Let me figure it out and summarize my ideas to make the quickstart/bootstrapping better.

[NiklasRosenstein]

Hey @melMass , sorry if the docs confused you. There's definitely room for improvement. 😄

pydoc-markdown --server --open -I .. 
> error: renderer 'MarkdownRenderer' cannot be used with --server

Are you sure your pydoc-markdown.yaml had the original state after pydoc-markdown --bootstrap mkdocs? Because then that error is weird because it should be using the MkDocsRenderer which can be used with --server.

[melMass]

Ahah, yes, I know how some things can seem obvious from the inside sometimes, that's why I created the issue!

---

This is my layout:

|- myLib
  |- Documentation
    |- pydoc-markdown.yml 
  |- pyproject.toml
  |- moduleA
    |- ..
  |- moduleB
    |- ..
  |- setup.py

and cat Documentation/pydoc-markdown.yml returns:

loaders:
  - type: python
processors:
  - type: filter
  - type: smart
  - type: crossref
renderer:
  type: mkdocs
  pages:
    - title: Home
      name: index
      source: README.md
    - title: API Documentation
      contents:
        - '*'
  mkdocs_config:
    mkdocs_config:
      site_name: My Project
      theme: readthedocs

All the commands I was referring to are issued from the Documentation folder (where the pydoc-markdown.yaml file reside)

[melMass]

Creating a README.md empty file in Documentation and running pydoc-markdown --server --open works:

But as soon as I add -I .. is fails with error: renderer 'MarkdownRenderer' cannot be used with --server

[NiklasRosenstein]

@melMass That is because if you use -I,--search-path it will not load the configuration file but instead fall back to using a default configuration that is aimed at producing Markdown content to stdout (hence the error about MarkdownRenderer). Though it would probably make sense to change the behavior here such that it always loads the config if it's present in the current directory.

https://github.com/NiklasRosenstein/pydoc-markdown/blob/924156a45975f138ca59442ca245c550becf371a/pydoc-markdown/src/pydoc_markdown/main.py#L295

You need to add the search path the your configuration like so:

loaders:
  - type: python
    search_path: [ .. ]
# ...

[melMass]

I did figure how to set the path in the meantime!

Oh ok I'm used to config files being loaded from $PWD by default and expected -I to be the python sources.

I think it all boils down to detecting existing poetry config file, and either add to the file, or notify the user with a link to the config doc for instance.

Just my two cents!

[NiklasRosenstein]

So the idea here is that Pydoc-Markdown can be used quickly from the terminal to generated some API documentation in Markdown right into stdout. If you do use a configuration file, it is expected that you don't need to make any additional changes to the way Pydoc-Markdown locates your source code and generates it. Thus the options like -I are supposed to be used only in this "quick & dirty" mode. 😄

About bootstrapping, there is definitely an issue right now when pyproject.toml already exists.

I would suggest that the user is asked whether the config should be appended to the TOML file. If the user says yes, we'll just load the templated config, convert it to TOML and append it. Otherwise, we can still write into a pydoc-markdown.yaml file and maybe need to make sure that if the YAML exists we use it instead of trying to load the config from the TOML.

About the -I option, I would prefer if we just showed a log-line to the user that the local configuration file is not actually used because they're using the "quick & dirty" CLI.

What do you think?

[melMass]

I would suggest that the user is asked whether the config should be appended to the TOML file. If the user says yes, we'll just load the templated config, convert it to TOML and append it. Otherwise, we can still write into a pydoc-markdown.yaml file and maybe need to make sure that if the YAML exists we use it instead of trying to load the config from the TOML.

Yes! I would go for the second one, creating the pydoc-markdown.yaml and tell the user something like:

> created pydoc-markdown.yml
> info: We detected a pyproject.toml, 
        note that you can use this file as your configuration.
        see https://github.com/NiklasRosenstein/pydoc-markdown/blob/develop/docs/configuration.md

Or maybe ask for user input as bootstrap would rarely be run headless (C.I etc...)

About the -I option, I would prefer if we just showed a log-line to the user that the local configuration file is not actually used because they're using the "quick & dirty" CLI.

Yes I think adding

> warning: using `-I` aka `search-path`, ignoring the config file.

can be useful.

Tbf the commands help is explaining things quite clearly, I was just confused by the bootstrapping/out-of-source documentation aspect of things.

I have yet to test, but I think it should be also stated that the generated files are store in a build folder. What happens if I run the command in the root of my project that already has a build folder? I don't see anything specific to that in the configuration doc.

Great job on this, it's exactly what I was looking for and it's much easier to integrate with custom tools than the other methods I tried.