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:
All my python function def's seem to be missing the function name?
No arg functions look really weird
On the bright side, the mobile version looks great and the search works better than my experience with Sphinx.
You can manually define the modules for portray (which you probably figured out to get documentation rendering):
And, yes write now Markdown only. I will say - this was a week only project: 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 :)
I've used it for two projects so far: documenting a relatively small python module, and for documenting a RESTful API. I do a lot of embedded work, so I'd like to use it as a place to document a piece of hardware in it's entirety, from schematics/layouts to firmware and build toolchains to actual use of the device. Do you (or anyone else reading this) have any comments on that use case?
I think my main complaint at the moment is that it doesn't play nice with Markdown, so I had to re-format a bunch of pre-existing documentation for it to work in Sphinx. ReST seems to render alright in Gitlab though, so that's a plus.
Haven't tried it yet but you should also be able to enable rst blocks through recommonmark so you get the best of both - https://recommonmark.readthedocs.io/en/latest/auto_structify...
from __future__ import annotations
I will give portray a try and see.
Is there any comparison between Sphinx-doc and portray?
But that's on the devs, not Sphinx, eh?
Enter this command to look for modules in a package, say, foopkg, and create .rst files to generate documentation for each module in the package and subpackages:
sphinx-apidoc --module-first -o docs/api foopkg
extensions = ['sphinx.ext.autodoc']
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
cd docs && make html
- Zero Config required
- Focus on Simplicity
https://timothycrosley.com/project-2-portray goes into why I created the project and how I viewed the current state of Python documentation tool.
Are you planning to support Restructured Text next to Markdown? I find ResT is used more often (in the machine learning ecosystem at least).
> 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!
portray is compatible with all MkDocs themes and plugins out-of-the-box
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.
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.
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.
 - https://github.com/mitmproxy/pdoc
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.
I'd be happy not seeing references to any religion and, quite frankly, I would hesitate to associate my employer with anything espousing religious dogma.
Its thousands of years old. Nazis have a bad name because they were fucking nazis!
The swastika is an ancient Sanskrit symbol which represents the churn of time and and the cycle of the universe.
Its really interesting to think about how the symbol has been coopted to be edited out of human conscience such that we dont recognize its symbology for the cycle of time and now its only associated with WWII
People are so stupid with symbology it boggles my mind:
Source: mayan order centurion, masons, rosicrucian.
Hint: if you change history by appending to it, it is not changing history it is writing it.
If you look back into history and check what happend, that is reading history.
If you want to delete lines that don’t fit your world view from the history, that is editing.
How would you go back to the original meaning of the swatsika without denying the existence of Nazi Germany and what it did?
(Greets from Germany btw)
Be convinced I thought enough about how much influence nazis have about my life, be it direct or by the positions I take to oppose them. And yeah: Nazis don’t go away of you don’t talk to them or ignore their existence. Just because you tolerate them won’t mean they will tolerate you.
And on the symbol: the swatsika in western culture is forever stained. This might be different if we were a grown up society that managed to deal properly with the past — but you can be sure that this week some young neo nazi tatoos the swatsika on their skin as a symbol of their racial hate — and while that is still going on a simple redefinition (that neo nazis would love to see), is frankly speaking naive.
They are paired mirror images, so they are both clockwise and counterclockwise.
I'll assume it's the former.
The reason why I'll assume it's the former is because we should always assume good faith - it's even a posting guideline on HN.
Also we are talking about a swatsika beeing used with near certainty in a western context. Maybe my reaction was indeed a little too “alergic” — I grew up in Austria and I have memories of Nazi grandfathers giving their neonazi ancestors all those nazi insignia. People who after the 10th beer start praising Hitler and demand new genozides, once they are in power again.
Given my background seeing somebody claiming their swatsika is not linked to nazis because it faces the wrong way is just something that doesn’t fly — I have heared that (and similar) excuses far too often from people who were definitly convinced nazis.
Btw. I don’t know if that guy is a nazi or someone who wants to provoke, but he certainly seems to know about the difference between right and left facing swatsika and thus could’ve anticipated the whole discussion.
But troll culture masquerading as innocent plausible-deniability really is ruining the internet because it's hard not to assume the worst (we see the same symbols being used on purpose to illicit a reaction and that person did respond with "Made you look. :grin:").
It's true that that swastika (usually going in the other direction) is a buddhist symbol, but it looks like the person who forked it is from Slovenia, which has never been a buddhist country but was briefly a Nazi country. It's hard to believe that was an accidental oversight.
Seems like he means well, but if he means that well, why not remove them?
The way your comment is phrased is disturbing.
Its not a problem of adoption. It's a problem of normalizing hate. If you don't understand that, I don't want to be associated with you.
Edit: Can I have any argument instead of simply downvoting me?
It is quite apparent that he knows about the meanings and uses of the symbol, therefore he could (and should) have anticipated the discussion. I grew up in an environment where nazi insignia are forbidden, and a very common way for convinced nazis to get around this was to just flip the damn thing and claim it is ok now, while in spirit you still go and use it to hail hitler with your friends.
I grew up in southern Austria next to the Slovenian border (which is where this guy is based). This part of Austria had a 40% right wing majority in the past and after a few beers right wingers still openly hail hitler in a pub, despite that beeing illegal. My grandfather who passed away a few years ago was a convinced nazi — this thing is still alive here.
The author is based in slovenia, literally a hour by car from where I lived. There is no way somebody from that area uses that symbol accidentally, without having considered its nazi connotations. This is an area where every other person had somebody in his family killed by nazis or were profiting from it in some way.
So either this person is incredibly naive and tries to overwrite history that is still very much ongoing or it is somebody who in full knowledge of all of this still decided to go with the symbol. In any way it doesn’t look good to me.
We're talking about an EU citizen, who is professing to be ignorant of what he learned in school, after he is informed about the issue.