[Pulp-dev] Building docs locally in dev-env?

[Brian Bouterse]

On Mon, May 11, 2020 at 4:40 PM Grant Gainey <ggainey at redhat.com> wrote:

> Hey folks,
>
> I am making some additions to the import-export docs and went to build
> them locally so I could review formatting. Since the last time I did this a
> month ago, I'm running into a problem.  docs/Makefile now assumes that "
> http://pulp/..." will resolve to something, which it certainly does not
> for my vagrant-box.
>
I expected it to use localhost:24817 as the location to fetch the openapi
schema from at docs-build time. For example I expect each plugin's makefile
to do that with a line like this one:
https://github.com/pulp/pulp_file/blob/master/docs/Makefile#L45


> Is this a problem with my env? A problem with the Makefile? Or a problem
> with the 'how to build the docs", docs, that is perhaps missing a step?
>
Are you running `make html`? What docs are you working from?


> I'm also getting two docstring errors:
>
> /home/vagrant/devel/pulpcore/pulpcore/app/models/exporter.py:docstring of
> pulpcore.app.models.PulpExport::more than one target found for
> cross-reference 'models.RepositoryVersion':
> pulpcore.app.models.RepositoryVersion,
> pulpcore.plugin.models.RepositoryVersion
>
>
> and
>
> /home/vagrant/devel/pulpcore/pulpcore/tasking/tasks.py:docstring of
> pulpcore.tasking.tasks.enqueue_with_reservation::more than one target found
> for cross-reference 'models.TaskGroup': pulpcore.app.models.TaskGroup,
> pulpcore.plugin.models.TaskGroup
>
>
> The solution is easy - explicitly specify pulpcore.app. But This didn't
> bite me last time I generated the docs, and I'd like to make sure it's not
> just a symptom of something More Wrong in my env
>
I don't think this is an error with your environment, but probably a
legitimate error. For anything we define in pulpcore and then import into
pulpcore.plugin we probably need to have the docstring use the full path.


> Thoughts, anyone?
>
> G
> --
> Grant Gainey
> Principal Software Engineer, Red Hat System Management Engineering
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20200511/462cf515/attachment.htm>