Integration of pycco in build scripts / "importable" pycco

[fbuchinger]

I'd like to import the pycco module in my own python build script, but currently there are a few show stoppers:

• there is no "entry point" function for pycco doc generation that I could invoke from my script (e.g. pycco.generate_docs(path_to_scriptdir))
• pycco assumes that you have cd'ed to your script directory before generating the docs, it can't handle absolute or relative paths... this isn't possible in build scripts
• there should be an option to specify the output path of the docs.

[Nick Fitzgerald]

Good points, when I get some time, I'll start working on this.

[Morgan Goose]

Made a branch for this. It's going to require some changes in the project layout to get it going well, if you want you can peruse what I've got already, but I still need to workout a paths issue when trying to process a file only using the imported module.

[fbuchinger]

@goosemo: thanks for working on this in your fork. I just checked your pycco.py and found that you still use Popen(["mkdir", "-p", "docs"]).wait() in your ensure_directory function. This isn't cross-platform , you 'd better resort to the python os.path functions for this.

IMHO the whole file/directory handling functions in docco are a bit ugly due to the lack of a decent path module in node.js. Thus, they shouldn't be copied 1:1 to python but rather be replaced by their more elegant python counterparts.

[Nick Fitzgerald]

Goosemo, just checked out your module branch. Everything looks great to me, should I merge it in?

[Morgan Goose]

I haven't messed with the paths stuff, and now the pycco docs are titled main.py, so I didn't know if thats what you'd want. It could be changes to be pycco, and the setup.y console hook could be updated to point to pycco:pycco, to make this so that the script was installed, and also have the docs titled properly.

[Nick Fitzgerald]

Goosemo, I cherry-picked the commit you made that did most of the work to make Pycco a module. I couldn't just branch off of your branch because it had some multiline stuff that I think is a "dead end" and not from your actual multi line branch.

I also added a --directory flag to specify the output directory.

Checkout this commit: http://github.com/fitzgen/pycco/commit/92534192cfc703adef75db77a8531c4226117567

Fbuchinger, shall I close this ticket?

[Nick Fitzgerald]

You mean that the main documentation is now named main.html instead of pycco.html? I don't think thats anything to lose sleep over.

[fbuchinger]

Thanks for the changes! I downloaded your commit but unfortunately the package generated by setup.py seems empty:

>>> import pycco
>>> dir (pycco)
['__builtins__', '__doc__', '__file__', '__loader__', '__name__', '__package__',
 '__path__']

[Nick Fitzgerald]

Thats because everything lives within the main.py module within the pycco module. I have added another commit which brings process in to the top level. process is the main entry point to the function which takes a list of filenames and user options. Let me know how that works for you.

[Morgan Goose]

@fitzgen Yeah, that and the title is also main.py. It can be fixed, but I've not messed with it.

I also merged in everything I've been doing with yours. But I need to poke into it more.

[Morgan Goose]

Right now though in the process def setting options=None is bad, since it's required to be there, in that it's looking for options.dir right after checking that sources is populated.

[Morgan Goose]

Python 2.6.2 (r262:71600, Jun 4 2010, 18:28:58)
So I did a bit of trickery to be able to use both:

diff --git a/pycco/main.py b/pycco/main.py
index 79626f3..c853959 100644
--- a/pycco/main.py
+++ b/pycco/main.py
@@ -196,7 +196,7 @@ def generate_html(source, sections, options):
     dest = destination(source, options)
     html = pycco_template({
         "title":       title,
-        "stylesheet":  path.relpath(path.join(options.dir, "pycco.css"),
+        "stylesheet":  path.relpath(path.join(options['dir'], "pycco.css"),
                                     path.split(dest)[0]),
         "sections":    sections,
         "source":     source,
@@ -292,14 +292,14 @@ def get_language(source):
 # Compute the destination HTML path for an input source file path. If the source
 # is `lib/example.py`, the HTML will be at `docs/example.html`
 def destination(filepath, options):
-    preserve_paths = options.paths
+    preserve_paths = options['paths']
     try:
         name = filepath.replace(filepath[ filepath.rindex("."): ], "")
     except ValueError:
         name = filepath
     if not preserve_paths:
         name = path.basename(name)
-    return path.join(options.dir, "%s.html" % name)
+    return path.join(options['dir'], "%s.html" % name)

 # Shift items off the front of the `list` until it is empty, then return
 # `default`.
@@ -331,11 +331,11 @@ highlight_end = "</pre></div>"

 # The bulk of the work is done here
 # For each source file passed in as an argument, generate the documentation.
-def process(sources, options=None):
+def process(sources, options):
     sources.sort()
     if sources:
-        ensure_directory(options.dir)
-        css = open(path.join(options.dir, "pycco.css"), "w")
+        ensure_directory(options['dir'])
+        css = open(path.join(options['dir'], "pycco.css"), "w")
     css.write(pycco_styles)
         css.close()

@@ -357,7 +357,7 @@ def main():
                       help='The output directory that the rendered files should go to.')

     opts, sources = parser.parse_args()
-    process(sources, opts)
+    process(sources, opts.__dict__)

 # Run the script.
 if __name__ == "__main__":

Now it'll accept a dict in process, and can better handle the use of optparse or not:

[GCC 4.4.3 20100127 (Red Hat 4.4.3-4)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import pycco
>>> pycco.process(['pycco/main.py'], {'dir':'docs', 'paths':''})
pycco = pycco/main.py -> docs/main.html

I guess if that's acceptable the next step would be to return html? instead of writing it out?

[Nick Fitzgerald]

This is great! And indeed returning html would be a nice next step. Perhaps instead of passing a dictionary, we should use **kwargs and make things a little more explicit and let people know when they are passing garbage keywords with an exception? I like this a lot.

Also, currently only process is being exported in __all__. Does anyone think anything else needs to be exported?

Maybe generate_documentation should return html rather than making files like we talked about and process can handle the creation of files since it already handles the css and directories.

[Morgan Goose]

I think that perhaps that'd be better for that for sure. I just wanted to keep it the same on the innards w/o having to warp thing too much.

I think that the html stuff may be something that the other open ticket has the html returned addressed. Haven't looked at the code too much.

[Nick Fitzgerald]

I made a few commits that made these changes:

generate_documentation will now return the html as a string.

Instead of passing the options dictionary around, we now pass keyword arguments. (This could still be cleaned up a bit, though)

Just check out my master branch.

In the mean time, I am closing this issue.