portray
Dev tools
documentation generator
SHOW HN2019
233points
81comments
#152of 2,195 in 2019
Top 7%of 2019 by points
How HN took it
MixedNo clear lean
9 positive, 12 neutral or asking, 1 mixed, 7 critical, out of 29 comments about the project. Thread score +0.16.
Execution: 1 for, 3 againstDesign: 2 for, 1 againstIdea: 2 for, 0 against
The thread, comment by comment
Each row is a top-level comment and its replies, in HN's order. Select a cell to open that comment on HN.
positive neutral or mixed critical about another commenter or something else the maker
What HN said
What people liked
Good mobile layout and search
From 1 comment
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…
danking00 on HN
Compatible with MkDocs themes
From 2 comments
Very neat, I especially like it's compability with mkdocs-themes. Will try this out on some project :)
hultner on HNhttps://timothycrosley.github.io/portray/docs/quick_start/4.-configuration/ portray is compatible with all MkDocs themes and plugins out-of-the-box
timothycrosley on HN
Objections
Swastika-like symbol in site footer and pdoc3 dependency raised concerns
From 3 comments
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/64 That's a hard pass from…
isbjorn16 on HNIt 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…
isbjorn16 on HNHis github profile picture is the swastika counter-clockwise. It's very clear from that his intention is to include things that appear like the Nazi swastika but are technically…
lucasmullens on HN
Only Markdown supported, no reStructuredText
From 2 comments
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…
timothycrosley on HNThis 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.…
gillesjacobs on HN
Requires packaged project; needs setup.py or pyproject
From 2 comments
I am confused, all I get is "No Python project found in the given directory".
MadWombat on HNmy 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…
MadWombat on HN
Slow generation on large projects
From 1 comment
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…
danking00 on HN
Requests
Support reStructuredText
From 1 comment
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.…
gillesjacobs on HN
Handle forward references in type hints
From 1 comment
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…
danking00 on HN
Questions
How does it compare to Sphinx
From 1 comment
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…
dragonsh on HN
How is search implemented
From 1 comment
How is the search implemented?
amjith on HN
Alternatives named
Sphinx
From 2 comments
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…
dragonsh on HNTried 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…
danking00 on HN
pdoc3
From 1 comment
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/64 That's a hard pass from…
isbjorn16 on HN
MkDocs
From 1 comment
portray uses MkDocs default search plugin which uses lunr.js behind the scenes.
timothycrosley on HN