What is Reddit's opinion of Sphinx?

From 3.5 billion Reddit comments

In general, Sphinx uses reStucturedText for markup/structure, so you could look up that documentation (also the Sphinx documentation on reStructuredText). It looks like a lot of the seaborn stuff is simply structural. I don't know about styling information/

Some excellent tips. I'd also add:

• Be comfortable with args and kwargs (as they're usually called...along with the corresponding * and ** operators) in case you need to be extremely flexible with function arguments.

• Use Sphinx to do the heavy lifting in arranging documentation for your projects. Brandon Rhodes has given classes on and written some excellent Sphinx tutorials: here's the code repo (including a link to a corresponding video), and here are some notes and exercises.

There is no official standard. Many companies define standards for their code, and many testing packages like pydoc and doctext define their standard too. Your example looks like the standard for the Sphinx documentation generator.

I spent some time evaluating Sphinx a few years ago.

I had no difficulty learning it (the tutorial is pretty thorough), but I ultimately was annoyed by the use of reStructuredText...my experiment with Sphinx is the only time I've come across this format, and I was constantly having to look at the references.

Finally decided it would be easier just to write my documentation by hand, since for the project in question Sphinx wasn't really doing much, and the time spent figuring out rST was not offset by the savings of Sphinx.

Your mileage may vary.

As for the prettiness of that other project....isn't that just good CSS choices?

Which is of no interest when you have a nontrivial build process e.g. if you want generated tables of content, if you have custom documentation directives, if your documentation build includes source-generated and source-extracted content, if you have specific styling or branding, if you use non-github markdown (because it doesn't support any of those features), etc…

Let me give an example: this is CPython's C-API allocation documentation as rendered by github, this is what it's supposed to look like because it uses Sphinx's C domain to provide cross-referencable documentation for C functions and structures.

I'd personally recommend using a documentation generator like Sphinx to get something up and running quickly (note: Sphinx isn't only for python, I've been using it recently to document this multi-language project with no obvious issues).

If the project you need to document is particularly big and involves many tiers, then treat the writing exercise as a top-down challenge. Write a top-level statement that describes the system in very broad terms (e.g. "persists bills to an SQL database") then go into more details as you learn more from your job.

Also, try and gauge from your new team whether they'd be happy with intermediate products. If they are, that's great: publish the top-level statements with a few diagrams (made with e.g. http://viz-js.com/) and continually refine from there. The biggest risk with documentation projects is when developers feel they need to have some super-perfect 100 % complete documentation: they end up spending weeks writing low-level documentation only to find that the code was nuked from prod months ago. An early, if scrappy, high-level attempt would smoke that information out early.

I've been trying to formulate a Sphinx-like documentation system as a build system in the style of the Build Systems a la Carte paper and it looks like I'd need something very much like Shake because you have dynamic dependencies (e.g. any document can refer to any other document, and you need to inspect them to discover these dependencies).

One major obstacle is that the documentation system needs to be extensible (e.g. like Pandoc with its readers and writers), so that a person can write a small plugin, and have custom build rules (e.g if it detects :graphviz:'foo.gv', then it runs graphviz on the file and then includes the image) and I'm not entirely sure if the flexibility offered by Shake is good enough here.

One funky thing here is that Sphinx's references are globally scoped -- while this seems ergonomic from the writer's perspective, this also means that you need to (in the worst-case) have scanned all documents before being able to resolve a reference. If someone did something like this in a PL, they'd probably be considered nutty by their peers today. I will most likely have explicit paths instead. However, this can introduce challenges while refactoring, so the "documentation compiler" should help the user with "hey, this path seems broken, perhaps you meant to use this other path?". I'm wondering whether these minor ergonomic changes will still fit in with the constraints of a Shake-like build system.

Sphinx is to my knowledge the most used tool. It has a bunch of plugins (like autodoc), generates documentation based on your code's docstrings and/or manual created documents.

Look at Projects Using Sphinx to see how widely used it is. Many large projects like Requests, Flask, Pandas, Matplotlib, Peewee, etc.

I made this one last winter using sphinx. Since it generates web pages for documentation from reStructuredText, I got away with doing nothing web related for the project. My recommendation is to put in as little effort as possible into style, so use html/css generators or css frameworks as much as possible and put most of your focus on writing content.

I'm sorry, I find it absolutely terrible, kilometers behind the quality of the worst Sphinx theme.

Here are shitty sphinx themes: http://www.sphinx-doc.org/en/stable/theming.html

and good ones : http://www.writethedocs.org/guide/tools/sphinx-themes/

I would suggest going the eBook route to save printing costs, overhead, and standardize inputs.

I have used Sphinxdoc before and I have a generic ebook template that uses sphinxdoc on GitHub. Pandoc is also popular.

You could give the students a simple template file for one recipe that they would need to rewrite that includes title, description, picture, ingredients list, and instructions. Cereal and milk would be a simple example that would not take away anyone's ideas.

In my experience, kids tend to get carried away with text editor features. By supplying a plain text template, the students would focus on the content and picture.

Sphinx is really your best way to go. Originally made for just python but now supports documentation for many languages and many of the features you talk about. Additionally the plugin set is pretty awesome; google styles code docs, thesis formatting docs, testing and validation, templating, etc.

http://www.sphinx-doc.org/en/master/

Maybe a bit heavy-handed for what you're trying to do but have a look at sphinx-doc.

It was made for documenting Python projects but these days it works pretty well for stand-alone documents too.

I cloned your repo and ran it on my Ubuntu 16.04 system with Python 3.5 (pip refused to install it because I don't have Python 3.6). It seems to run fine and looks good, though when scrolling around I pretty routinely hit some out-of-bounds conditions; ditto when I fired the gun in ecs_demo.py and it reached the edge of the screen; not sure if there's just no bounds checking yet, or if that somehow doesn't work on Python 3.5. Love your ASCII cowboy!

You do seem to have some pretty thorough docstrings so you can get some pretty decent documentation built really quickly by just pointing something like Sphinx at it. Wouldn't be hard even to have it dump those into a docs directory in your project and then set up GitHub Pages to host from there. With basically no other effort you'd get module documentation kind of like what you see in this little library of mine; the rest of the pages there I wrote as Markdown.

For me personally, yes I would be interested in a library like this, but for me to consider using it for a project it would at least need the requirements knocked down to Python 3.5; in my experience that's by far the most commonly available version of Python 3 on Linux systems, with some not even having a 3.6 available in their repos yet. I suppose it's worth mentioning that I'm not currently working on a project for which this would be useful (well, I haven't settled on what I'll be using for display for Rogue Trader yet, but I am leaning away from ASCII...), so take this as you will.

The code is not very pythonic in many ways.

• Files should almost always opened using the with open (...) as fobj idiom. That way the file gets closed properly.
• strings should not be concatenated wit the + operator. Use da list and then the string.join method
• for short dynamic strings use placeholders and the .format method. Much more readable than the used endless fragments of strings and values concatenated with +
• The template based approach could be enhanced by using a real template engine, like jinja.
• use a proper command line parsing lib, like the argparse module from the stdlib.
• the main function is too long
• the way you deal with the different kind of annotations feels nor well crafted. Imagine how the code becomes an even more spaghetti look, if you need to add more tags? Better use a dispatching dictionary to map tags to handler functions!

Last but not least: I don't like the syntax of your annotations. It feels and looks clumsy. But that's of course a personal taste. Besides doxygen one could also use Sphinx for C++ projects.

Most of my textbooks can be found as international editions for much less than the "official prices." My semiconductor physics book was less than 20 dollars for the Indian version, but more than 200 for the American one. There was a supreme court case that ruled that the International edition books can be sold legally in the US, regardless of any scary warning on the front.

I always prefer hard copy. Easier to read, understand the content, annotate if necessary, flip through, etc. Transporting heavy books can be an issue but I almost always keep my books in my apartment.

I've used bigwords.com to find most of my textbooks, international when I can find them, "gently used" and less than half the normal price when I can't. I don't think I have ever paid more than 100 dollars for a textbook the past 3 years, and I only paid up to that much for an optional textbook (in terms of the class) that is considered a fundamental for the discipline I am studying.

I often will have both, btw. I have pdfs of almost all my books on my phone, so I can do homework wherever I go, regardless of whether or not I have the book with me.

EDIT:

Just wanted to mention Sphinx. It's a python tool that makes pretty good documentation (you might see it on readthedocs.org). There have been a few texbooks implemented using it, here is one: http://www.theoretical-physics.net/dev/index.html

Sphinx Page: http://www.sphinx-doc.org/en/stable/index.html

Pandoc is a great tool! I've written a fair amount of documentation with it.

I've also used Sphinx with pretty good success, although it's based on RestructuredText instead of Markdown. It was originally made for API documentation, but it also works great for standalone documents. Sphinx has a bunch of really nice HTML templates as well.

In my experience, Pandoc is great until you start to want complicated documents with multiple inclusions and whatnot. Also, Sphinx is Python-based instead of Haskell-based, which means you can install it with pip.

Huh. I was actually planning something similar for when I migrate from WordPress to a static site generator, but my plans were to reverse-engineer the index format that Sphinx generates for its JavaScript-based search and then borrow that code as a target for a custom index generator.

(I settled on that plan before rustdoc came out, so it was the only liberally licensed JavaScript-based search code I knew.)

I'm showing them in community.

python-sphinx 2.2.0-1 Package Actions Source Files / View Changes Bug Reports / Add New Bug Search Wiki Security Issues Flag Package Out-of-Date (?) Download From Mirror Architecture: any Repository: Community Description: Python documentation generator Upstream URL: http://www.sphinx-doc.org/ License(s): BSD Maintainers: Johannes Löthberg Daniel M. Capella Package Size: 1.5 MB Installed Size: 16.1 MB Last Packager: Daniel M. Capella Build Date: 2019-08-18 17:06 UTC Signed By: Daniel M. Capella Signature Date: 2019-08-18 17:11 UTC Last Updated: 2019-08-18 17:13 UTC

python-sphinx_rtd_theme 0.4.3-1 Package Actions Source Files / View Changes Bug Reports / Add New Bug Search Wiki Security Issues Flag Package Out-of-Date (?) Download From Mirror Architecture: any Repository: Community Split Packages: python2-sphinx_rtd_theme Description: Python Sphinx Read The Docs Theme Upstream URL: https://github.com/rtfd/sphinx_rtd_theme/ License(s): MIT Maintainers: Johannes Löthberg Package Size: 4.3 MB Installed Size: 7.2 MB Last Packager: Johannes Löthberg Build Date: 2019-02-15 13:25 UTC Signed By: Johannes Löthberg Signature Date: 2019-02-15 13:25 UTC Last Updated: 2019-02-15 13:27 UTC

Actually this is auto generated html files by sphinx ( http://www.sphinx-doc.org/en/master/ ), from documents stored in kernel tree, it can be generated as pdf or other formats like latex. If you have a vision how to improve it, why won't you do it on that level?

In embedded I used Doxygen, but I consider switching to Sphinx (http://www.sphinx-doc.org/en/master/) - I use it to document Python projects, but it can also document C/C++. Didn't make a feature comparison yet, though.

This sub is not for stuff like this, you might want to try /r/learnpython or stackoverflow.

In any case, did you read the official docs on templating and theming? I suggest looking at some existing theme, like Read the Docs Sphinx Theme how they do it. Customization in Sphinx is a bit tricky.

Nice to see an effort being made towards documenting Anki's source code.

I suggest the use of docstrings in the source files instead of creating seperate files.

spinx-autodoc can automatically create nice html documentation from docstrings.

Then don't let anyone edit the book. You have fine-grained control over read and write permissions for the whole wiki, or even individual groups and pages. You can use only passwords, or passwords and usernames.

If you don't want the site to be editable through the web at all, including by you, then look for a static generator, like Sphinx.

Working on understanding Sphinx extensions. I'm using a few that I would like to contribute to but am having trouble understanding the code or the best way to develop against Sphinx.

>The problem with markdown is that it doesn't really have a spec

For more info on that, read Eric Holscher's great post on Why You Shouldn’t Use “Markdown” for Documentation

>I'm so glad python has made some moves towards markdown for documentation

Away from reStructuredText? Do you have evidence of that you can point to out of curiosity?

You can make one using Python Sphinx package. Write the content in rst format and run sphinx to get HTML. This can be copied to your client's server. Sphinx: http://www.sphinx-doc.org/en/master/ A Tutorial: https://pythonhosted.org/an_example_pypi_project/sphinx.html

When you write python code, you can write docblocks.

def sendMail(self, toAddr, fromAddr): ''' This is a python docblock/docstring example. Here I describe what my function does, what parameters it uses. Any return codes for failure or success '''

Sphinx Is a python framework for turning those docstrings into a ReadTheDocs like this

This way you never have to write documentation separately, which makes sense because you are right there in the code looking at in anyhow.

Generate restructured text (.rst files) and convert to HTML with Sphinx http://www.sphinx-doc.org/en/master/index.html. Edit: great thing about Sphinx is that you can easily switch between output formats (pdf, doc, etc).

That documentation was generated by an open source program called Sphinx http://www.sphinx-doc.org/en/stable/ In fact, it uses the default Sphinx theme.

However it is not a wiki, but a static site, so it might not what you are looking for

Generating docstrings that only restate the code with no added insight seems like a waste of time. I would recommend first looking into documentation generators like pydoc or Sphinx to see what they are capable of generating from the code alone, and then after that decide what information (if any) you need to add to your docstrings.

To be clear, I definitely recommend adding docstrings that contain human insight and useful tips; those can be extremely useful. I just don't think it's worth it to have docstrings that simply restate the code.

Just a tip: If you use something like Sphinx--which is used in a lot of Python documentation--you can support all these things and more. It's a very powerful tool made for writing static programmer's documentation but you don't have to use it that way. I've used it as a static site generator in the past and what's really great about it for something like Minepad is you could let users write their stuff in Notepad++ (or any text editor) and have things like tables of contents (ToC) and other links-within-the-document taken care of automatically...

.. toctree:: :maxdepth: 2

Some Section Title ============ Content here with images links, and everything!

Some subsection title ------------------------ Some sub-topic inside the main section. You get the idea.

I don't know what back-end you're using but that right there is just reStructuredText (.rst). Lots of content management tools support it or have plugins to handle it.