Use portray to build a beautiful documentation site with less work

[timothycrosley]

Hey Tim, it's Tim!

I thought a project I built recently, might be useful to better showcase your project: https://github.com/timothycrosley/portray
Switches to using portray and github pages to host your documentation site (link to site will need to be updated if accepted).

Let me know what you think, and how you're doing.

Thanks!

~Tim

[kata198]

Wassup, Tim!

Looks pretty cool, I'll check it out! Thanks!

One thing I notice, and maybe I'm doing it wrong, but it seems to be broken on my local in-dev version:

I've reduced the steps to the minimum I can find to reproduce, and I can reproduce the error by the following:

1. git clone https://github.com/kata198/AdvancedHTMLParser

2. cd AdvancedHTMLParser

3. mkdir AdvancedHTMLParser/xpath

4. touch AdvancedHTMLParser/xpath/__init__.py

5. portray as_html

It doesn't matter what is in that __init__.py, whether or not it is imported from the main package, defined in setup.py, MANIFEST.in; none of these seems to "fix it."

I get this error:

Done Copying source documentation to temporary compilation directory
Module not found: AdvancedHTMLParser.xpath
(myenv)

It does also warn me that there is no config file found, so maybe it is fixable through some directive there, but item #1 on the portray readme is "no configuration required" :)

Works great in a flat module, however!

I assume there is some way to toggle some things (methods, etc.) as visible / non-visible, I'll have to look into that, as well as improving some of the output here. Like the "Formatter" sub-page, for example, is way too busy and has reference to python core source code, etc.

The current pydocs view is also very overwhelmed, I need to do a rehaul of the documentation here. It's fairly complete and well-documented, but just not well-organized.

.

A feature request(s), might be easy for you to implement:

So, the links on the sidebar to different modules within the package (for this project, it includes names like "Formatter", "Parser", "Tags" -- can these be made to retain case? So, for example, there's a module within this package called "SpecialAttributes.py" with the camel casing, but on the generated docs it appears as "Specialattributes." Seems to me like documentation should have the same name, even if the PEPs on what the "right style" for naming are keeps changing.

Second, in the same realm: the sidebar links themselves link to just the folder, so for example: href="../Parser/" This works fine on a web server, which would then search for the index page (index.html) and display that, but for offline copies (how I almost always view the docs) I get a browser-generated index page of that directory, since no active server to forward to the index page. Is this configurable / can it be made to go direct?

I didn't spend a whole lot of time looking, but I didn't see where these items were being generated directly from portray. Seems to be one of the underlying libraries?

.

Anyway, thanks a lot! I'm going to look into this more, and will probably make it available for the next mid-level release!

Shoot me an email on my gmail when you get a chance, as well.

Have a great day!

---

EDIT: Properly escaped __init__ in text