Opened 4 years ago

Last modified 4 years ago

#7010 enhancement new

Allow building apidocs for a sub-project or a single file

Reported by: Adi Roiban Owned by: Adi Roiban
Priority: normal Milestone:
Component: release management Keywords:
Cc: radix Branch:
Author:

Description (last modified by Adi Roiban)

When I change some epydoc documentation I would like to see the result.

Right now, this means building whole documentation.

It would be nice to be able to call apidocs generation for a single file or at least a folder.

I have attached a patch which does a quick prototype

# Should produce the same result as previous version.
./bin/admin/build-apidocs . apidocs

# Will only generate apidoc for twisted/web/proxy.py file
./bin/admin/build-apidocs twisted/web/proxy.py apidocs

# Will only generate apidoc for twisted/web sub-project
./bin/admin/build-apidocs twisted/web apidocs

As a final result, I would like to be able to call the command as:

./bin/admin/build-apidocs --output-dir=apidocs twisted/sub/file.py twisted/file2.py

In this way I can use the VC system to get a list of files changes since origin/trunk and run apidocs only on those files.

What do you think?

Does it make sense?

Do you find it useful?

Is there a better way to get the same result?

Maybe this should not be an admin command.

Thanks!

Attachments (1)

7010-1.diff (1.7 KB) - added by Adi Roiban 4 years ago.

Download all attachments as: .zip

Change History (6)

comment:1 Changed 4 years ago by DefaultCC Plugin

Cc: radix added

comment:2 Changed 4 years ago by Adi Roiban

Description: modified (diff)

I have attached a quick hack, but based on feedback from initial review I would like to do a full implementation.

Thanks!

comment:3 Changed 4 years ago by Adi Roiban

Summary: Allow building apidocs for a sub-project of single fileAllow building apidocs for a sub-project or a single file

Changed 4 years ago by Adi Roiban

Attachment: 7010-1.diff added

comment:4 Changed 4 years ago by Jean-Paul Calderone

What does this do when the included files contain links to APIs defined by excluded files?

comment:5 Changed 4 years ago by Adi Roiban

Keywords: review removed
Owner: set to Adi Roiban

In current version it receives an 'invalid ref to' error.

... will think at a way to fix these kind of errors... maybe this would require a patch in pydoctor.

One reason why I want to run pydoctor on specific files/folders to that I could start fixing all errors in twisted projects and have a clean build.

But like you said, maybe running full build is faster in this case.

Another reason why I want this is to have a very fast pydoctor which can run only on files changed during development of a branch.

Thanks for the feedback!

Note: See TracTickets for help on using tickets.