
Show HN: Zero-Config Documentation Websites for Python - timothycrosley
https://timothycrosley.github.io/portray/
======
danking00
Tried this on our project, GitHub.com/hail-is/hail.

Sphinx is a persistent thorn in our side, but we've made it work. A couple
things I had to do to get this working:

\- something thinks a filename with dots (e.g. example.8bits.bgen) means there
is a python module that needs to be imported (e.g. example), and fails when
that does not exist; we have files like this in a data directory

\- I could not quickly figure out how to ignore files, so I had to delete a
Sphinx conf.py file.

\- Sphinx resolves the _templates folder relative to where it is called, not
relative to the doc string's source file, so I had to add several symlinks
(rather than manually edit every doc string).

\---

OK docs are generating. Quite slow, maybe a couple minutes. Looks like one
core is at 100% during this process. We've got ~400 files. Maybe its parsing
some data files? The whole directory is 318 MB.

\---

Now I'm looking at the docs.

First thing I notice is that Python type hint forward references break
everything. Consider:

    
    
        class GroupedMatrixTable(
            parent: 'MatrixTable',
            ...
    
    

The generated doc page is missing the class name and the entire class
definition is inlined as a preformatted block (with highlighting :shrug:).

All my python function def's seem to be missing the function name?

No arg functions look really weird

    
    
        def (
        )
    
    

So all our docs are in ReST (thanks Sphinx :|). This means they're not valid
Markdown. It seems that invalid markdown in a class doc string can break the
formatting of all the methods (presenting them again as one reformatted
block).

\---

On the bright side, the mobile version looks great and the search works better
than my experience with Sphinx.

EDIT: formatting

~~~
timothycrosley
Thanks so much for this great feedback! I haven't done any speed optimization
on portray yet - as both at work and online I tend to organize my own projects
as small self contained repositories. Clearly there is a lot of room for
improvement there, I have a lot of ideas to make it faster.

You can manually define the modules for portray (which you probably figured
out to get documentation rendering):
[https://timothycrosley.github.io/portray/docs/quick_start/4....](https://timothycrosley.github.io/portray/docs/quick_start/4.-configuration/)

And, yes write now Markdown only. I will say - this was a week only project:
[https://timothycrosley.com/project-2-portray](https://timothycrosley.com/project-2-portray)
so I think there's a good chance I could improve these points with one more
week of time spent :)

Thanks!

~Timothy

~~~
danking00
Yeah of course! In retrospect my initial post seems a bit neutral to negative.
I'm really glad this project exists, I'm endlessly frustrated by Sphinx. I'll
keep my eye on your project!

------
dragonsh
My team at present use sphinx-doc[1] and generate both HTML and PDF. We write
the documentation as part of the code using docstring and then other documents
manually in rst. We use Sphinx plugin to automatically generate document from
code.

I will give portray a try and see.

Is there any comparison between Sphinx-doc and portray?

[1] [http://www.sphinx-doc.org/en/master/](http://www.sphinx-
doc.org/en/master/)

~~~
weberc2
We've historically done this as well. One issue we perpetually run into is
that the docstrings get out of sync with the actual signature / types of the
methods/etc that they purport to document. I suspect there are plugins that
generate documentation from types such that there is less to keep
synchronized. It is also unfortunate that Python projects have to set up
infrastructure to build and publish documentation packages. I really like the
effortlessness that Go's ecosystem
brings--[https://godoc.org](https://godoc.org) just reads your source code
from your git repository, so there is are no explicit steps for building and
publishing documentation.

~~~
carapace
> the docstrings get out of sync with the actual signature / types of the
> methods/etc that they purport to document

But that's on the devs, not Sphinx, eh?

~~~
weberc2
It's kind of on the whole dynamically typed model. If you can have static type
annotations that are validated for correctness, then you can use those
annotations to validate or generate your documentation. Python supports
annotations and validation thereof via Mypy, and assuming the project takes
advantage of these, then Sphinx could leverage them to validate/generate
documentation.

------
gillesjacobs
This is great! You hit the need for configless docsites that many Pythonistas
who are in data science and research have: we write a lot of experimental and
prototype code. Docstring documentation in itself feels like a considerable
investment in these contexts so anything that helps publication without any
hassle is more than welcome.

Are you planning to support Restructured Text next to Markdown? I find ResT is
used more often (in the machine learning ecosystem at least).

~~~
timothycrosley
Thanks!

> Are you planning to support Restructured Text next to Markdown?

I will look into supporting this, I agree that it definitely makes sense as a
feature!

------
noobiemcfoob
I just used this on a random project I happen to be building documentation
for. I'm pretty in love with the minimalism of 'portray'. I wish there was a
chance to get my team to use it, but I'll definitely be using it in my
personal projects going forward!

------
contravariant
It's always kind of interesting to look at a document created by the tool it's
describing.

~~~
ByThyGrace
I thought the GIF within a GIF was very clever. Did you notice? It's "playing"
itself back.

~~~
jedberg
I think the number of playbacks is the number of times they had to re-record
the video. :)

~~~
timothycrosley
Ha, I wish it was accidental! In reality, I created the gif many more times
than needed just because I wanted to create the effect.

------
hultner
Very neat, I especially like it's compability with mkdocs-themes. Will try
this out on some project :)

------
MadWombat
I am confused, all I get is "No Python project found in the given directory".

~~~
timothycrosley
portray requires your project to be packaged for it's auto discovery - if you
get this error and your project has a setup.py or pyproject.yaml in the root
(and this is where you ran portray from) let me know and I'll create a ticket!
Otherwise - I highly encourage looking at using poetry to setup your
pyproject.yaml file: [https://poetry.eustace.io/](https://poetry.eustace.io/)

~~~
MadWombat
my project doesn't have a setup.py because it is not intended for packaging
and it doesn't have a pyproject.yaml because to be honest, this is the first
time I heard about such a file. But then again, the title says "zero-config".

~~~
timothycrosley
portray no longer requires a config to be present, instead you can just
specify modules directly from the command line with `-m`:
[https://timothycrosley.github.io/portray/TROUBLESHOOTING/#no...](https://timothycrosley.github.io/portray/TROUBLESHOOTING/#noprojectfound)

------
peteretep
Excited to try this. From a Perl background, used to POD, Python's doc systems
have been a sewer.

------
amjith
How is the search implemented?

~~~
timothycrosley
portray uses MkDocs default search plugin which uses lunr.js behind the
scenes.

------
fucking_tragedy
How easy is it to theme for when Material starts looking dated?

~~~
timothycrosley
[https://timothycrosley.github.io/portray/docs/quick_start/4....](https://timothycrosley.github.io/portray/docs/quick_start/4.-configuration/)

portray is compatible with all MkDocs themes and plugins out-of-the-box

~~~
fucking_tragedy
Awesome, looking forward to trying this out on a new project.

------
abakus
Kudos to using toml for configuration.

------
isbjorn16
I was super pumped by this, and took some time to look into pdoc3 too.

\-
[https://github.com/pdoc3/pdoc/issues/87](https://github.com/pdoc3/pdoc/issues/87)

\-
[https://github.com/pdoc3/pdoc/issues/64](https://github.com/pdoc3/pdoc/issues/64)

That's a hard pass from me. I'm not going to link my employer's name (much
less my own name) to anything with a swastika on it.

~~~
krilly
There is no question that these are Buddhist swastikas; they are clockwise and
also rotated 45 degrees compared to the most common nazi version.

It is difficult to appreciate how ubiquitous swastikas are in the Buddhist
world until you go there and see them everywhere. I have no doubt that this
was an innocent decision.

~~~
isbjorn16
It stopped being an innocent decision once it was pointed out and he doubled
down.

Put another way: I cannot put my or my employer's interests in Western markets
at risk because something is acceptable in Eastern markets. The maintainer can
do whatever he wants to do; I'm not questioning that. I'm just saying I won't
be using it, even if it would save me from sphinx-autodoc fragility.

~~~
peterwwillis
> I cannot put my or my employer's interests in Western markets at risk
> because something is acceptable in Eastern markets

My employer works in both markets, so rejecting something because it's Eastern
would look much worse than rejecting it because someone in one market might
not know what it is.

Anyway, it's a tiny icon on the boiler plate of a dependency of a project used
to generate documentation. It would be a huge stretch to say your employer
supports Nazis because of this.

~~~
isbjorn16
I highly doubt the absence of any religious iconography is going to harm my
employer in eastern markets.

