What is Reddit's opinion of
Read The Docs?
From 3.5 billion Reddit comments
➔ Read The Docs website
By popularity on Reddit, this Service is:
44 reviews of this app found across Reddit:
I feel the same way. "Read the types" people say, but that's often coming from people who already grok them. Coming from the other side is much harder. Hackage has a clunky documentation interface, IMHO. I wish it used something a little more common (like Markdown) and looked prettier. Do we have much of a presence on https://readthedocs.org/? Examples are key.
The idris docs linked are themed via readthedocs (https://readthedocs.org/) -- I think we can probably just hook up a readthedocs instance for ghc now that we have this doc build method, and get that on top of whatever we now have, tied to different tags, etc.
I understand agda is moving to use that system as well.
For me, the best solution is to go with https://readthedocs.com. It's the commercial, private docs hosting arm of https://readthedocs.org.
Why go with them?
- It helps support https://readthedocs.org
- I would rather be writing my own code then setting up stuff to serve private documentation
SourceForge alternative for source hosting ie version control? GitHub, FOSSHub, BitBucket, etc. = all good options
SourceForge alternative for documentation hosting? Readthedocs
SourceForge alternative for binary downloads? 14 options that either completely suck or cripple themselves to make sure that an alternative doesn't exist.
Ok, it has to be asked - why bother when the Python community has sphinx?
One of the greatest complaints we hear in the scientific community when trying to convince our peers to try Python in lieu of Matlab is the lack of centralized, comprehensive documentation for the various libraries they need. That's slowly changing with readthedocs and other projects, but how is introducing another documentation system going to improve the ecosystem? What does Doxygen offer that the existing Python documentation system doesn't?
/u/K900_ Gave a good link there, but for the future, there are a few ways you can get more information about a library. You can usually find information on Github. If they have a README, you are probably in good shape. You can also look on readthedocs. If neither of those options exist, you can look for a tutorial with a Google search. Sometimes the developers will host their documentation on their own website. A Google search will help you fid that.
Next you should look at the source code and hope they have documented it well. You can try to read through the source, but that can be difficult for a new programmer. It definitely helps you learn a lot though.
You can use help as you already discovered, and there is also a function dir which you can pass an object to and get all it's attributes and methods.
With dir you can do something like:
import requests print(dir(requests.get))
I recommend you use pprint with this to make it easier to read.
import requests from pprint import pprint
pprint(dir(requests.get))
There is also the ability to print the docstrings using __doc__. For example:
import requests
print(requests.doc)
I agree with this sentiment. In the Python world, a tool called Sphinx (http://www.pocoo.org/projects/sphinx/) is often used to write in-tree documentation, and render it (to HTML, LaTeX/PDF,...),... Note Sphinx is not Python-specific, though it has more built-in support for it. I prefer the ReST format it uses over Markdown myself because ReST provides some more semantical markup support, and is more extensible. Tools like ReadTheDocs (https://readthedocs.org/) can automate and centralize these documents, in different formats for different branches etc.
It's great to read these regular updates. I'm really looking forward to opam-in-a-box, especially for packaging up programs for Windows users.
I haven't paid any attention to opam-doc, but it'd be great to have something similar to Read the Docs or Hackage.
If I may put here a tiny small criticism at the community, sometimes I think a portion of the blame for this feeling rests on the style of documentation people make for their libraries.
Sometimes there's only a hackage page, with types and the barest of descriptions, if any. And this is true even for some popular libraries. The user is tasked with finding out which functions are actually the most important, what are the "entry points", or what does the names of the functions mean.
I realize documentation is a boring, slow, time consuming and expensive job. Also, it seems to me that there's no standard place to put documentation on (when we are talking about docs that are not only hackage style API docs).
But it goes a long way on helping people use a library or framework when you have an actual manual, explaining the concepts,what are expected functionalities, some basic examples and patterns to scale from there.
Python's community have places like readthedocs.org where people share docs on python libraries. One main difference with respect to hackage is that the API docs are NOT the most important feature of each docs, but the actual manuals for the libraries. I think something like that would be very helpful.
Of course for Haskell, the documentation of the types and API is a lot more critical than for python. But it is not all. There should be some more Textual description of the concepts that lead to that design and how to combine the pieces and use them.
As an example, the Flask web framework has one of the best documentations I know of. I realize that a nicely type API would reduce this docs to probably a third of its current length + simple API docs. But it wouldn't be just API docs.
A community effort to build better docs to commonly used libraries would be very nice, and I would gladly help with that if there's traction.
Depending on your definition of "affordable", look at Confluence. I use that for all our internal documentation and it's a great product.
Depending on your audience and the type of documentation you're producing, there are options like Github Pages, Read The Docs, and even something like a MediaWiki install. You could even go with a static site generator.
If you could clarify a bit as to who you're writing for and what the end goal is (user docs, developer doc, online forum for a community project, etc...), it might be easier to make recommendations.
The new Docs walk you through the entire process of creating a new Skill: https://mycroft.ai/documentation/skills/introduction-developing-skills/
The API auto-generated docs are at: https://readthedocs.org/projects/mycroft-core/
readthedocs. If you use iPython you can try my_function?, or more generally help(my_function). If it's some code that a friend or colleague wrote, pray they wrote the documentation properly.
You can download the official docs as a PDF or epub from https://readthedocs.org/. I converted the epub to mobi and I read it on my kindle when I need to. It is very well written.
https://readthedocs.org/ is a possibility.
Have the details in github, and have that publishing to read the docs.
People who want to contribute can fork the repo, edit, then submit a pull request. (you can have a team in charge of accepting the requests.)
As a dev, I would really love to see some improvement here. Even the /help/documentation page doesn't offer easily navigable information (hard link throughs, no search... list goes on) - really encourage you to check out https://readthedocs.org/ as M2 is OSS.
For pip packages, try PyPi. For documentation, many packages have their own, but Read the Docs has a really good collection of them in one clean good site.
Funny, I was wondering the exact same thing yesterday... I was looking at this one, it helped a little:
https://readthedocs.org/projects/cubicsdr/downloads/pdf/latest/
I'm trying CubicSDR as an alternative to SDR# since that program is unstable and invariably ends up freezing and/or crashing.
IMO, the minimalist interface in CubicSDR makes it a PITA to figure out. Every control is a mouse gesture or keyboard shortcut within each pane, and the closest thing to instructions are hover text boxes that time out after a few seconds.
Edit: BTW, I dunno what your hardware/software setup is, but for me (Windows 10, Noolec NESDR Mini 2) the 64-bit version wouldn't recognize my SDR device, but the 32-bit version would.
Holy shit ReadMe.io is expensive. For that price it better come with one of those documentation-writing AIs mentioned in another post here.
I just took a look at Docusaurus.io and that seems like a solid choice. You can build locally and publish to GitHub pages or another hosting site. If you're looking for a hosted solution, Read the Docs might be a good choice. If you're hosting your app at GitHub, GitLab, or Bitbucket they all have wikis available, and of course GitHub has GitHub Pages. I think GitLab now has something similar too.
>I am just wondering what everyone uses.
Honestly we use whatever our employer has decided on. A lot of times these kinds of decisions are based on how and where the application itself is hosted, and the people who decide those kinds of things are not the person over in the corner writing the documentation. At a previous job all my documentation went into the knowledge base that shipped with our issue ticketing system, and at my current job my docs live in the same web space as our SaaS platform and I was told "...you upload to this IP."
If you came to me and said, "....hey, write the docs for this project, host them wherever..." the first place I'd look is wherever the project was hosted, and if that wasn't doable the I think that Docusaurus would be my next choice, followed by a wiki like MediaWiki.
> As much as this seems better than previous iteration (ugh), it's still quite terrible for modern standards (proportions, spacing, alignments, layout itself... list goes on, but worst offender - it's really hard to read).
As always, your positive, uplifting and constructive feedback is always welcome. Unfortunately in this case I'm reasonably sure that the contributors who provided the theme are not reading your comment
> Why not just use https://readthedocs.org which editing could be done by anyone through git pull requests and then approved by openSUSE team?
There is no "openSUSE Team" besides volunteers
Those are the same volunteers you accuse of causing a big mess by editing a wiki
I have no problem with suggestions regarding using new tools or processes, but the question ultimately leads to the same place - Who is going to do it?
I won't, I have enough on my plate. If you want to set that up, encourage the whole community to start using it, and establish it as the defacto perfect documentation solution, please go ahead
Document DirectX 11 API (Microsoft is really bad in creating documentation) for https://github.com/doitsujin/dxvk project in https://readthedocs.org/ format. Just beware of copyrights so you must create it from scratch without looking at Microsoft page :P
While I love the advertising model presented here, and hope that it will spread to other sites, I'm sad it starts with Read the Docs. No matter how sober it is, the point of advertising is to be somewhere in your eyesight and somehow catch your attention, or at least borrow it for a little moment, which is absolutely not what you need when you read a documentation. In this case it's an annoyance.
I'd like a bit more transparency about the motivation behind this move from Read the Docs. I've found their Sustainability page to be a good start.
Hi /u/schedutron
It would be really helpful to have a real documentation either directly in your README file and in something like https://readthedocs.org/
For now I am just not able to understand what you project is doing ^^
I would like to recommend celery docs for a thorough grounding in what Celery is and how it works.
I imagine you will end up with a web request-response that queues the task, a celery worker will then pick up the task from the queue and do the processing, then there will be some mechanism for you to receive the result.
I wouldn't say the documentation is bad, at least it's there, I know plenty of projects that just say "Documentation: See source code.". It doesn't have as much examples as I would like, but at least the search works and it seems logically broken apart (Search doesn't even work in Doctrine).
It's always nice to have alternatives, this looks like a nice alternative to Laravel.
Look into https://readthedocs.org
We use git and sphinx with a custom theme for in house technical documentation. (you can theme sphinx so that it doesn't look like it's from 1993, there are themes out there or you can customize it yourself).
Maybe Sphinx is overkill but either way you go about it having some kind of version control for a large technical doc is important and should be the first consideration.
j 1b jumps to the nearest label 1: in a backwards direction (compared to the instruction that would be run if there wasn't a jump). j 1f similarly jumps forwards to the nearest label 1:. You'll see one of those in the fib function. You can have as many label 1: to 9: as you want -- saves having to make up meaningful names for minor local jumping. Especially handy in macros that might be expanded in many places.
I don't actually know how verilator is usually exited. The tohost/fromhost thing is also used (at Berkeley) on actual test chips and FPGAs. Perhaps on real hardware there will be actual physical registers at known addresses, but for Spike they're just anywhere in RAM and Spike finds them using the ELF metadata.
This seems like some useful documentation of a few things:
https://readthedocs.org/projects/chipyard/downloads/pdf/dev/
If your documentation is too complex to fit in the README, then I would incorporate documentation generation tools like sphinx and include instructions for building the docs and hosting them online somewhere like https://readthedocs.org/
+1 /u/Hungry_Check_9153
Go here: https://readthedocs.org/projects/django/
Find your version. Then read/do the tutorial and read the docs. If you look at the settings file, the previous versions used to include a link in there when you are actually ready to deploy
# See https://docs.djangoproject.com/en/3.0/howto/deployment/checklist/
Yes, absolutely. As I say, it's a small thing to bitch about.
I've been guilty of this myself. (And the other way - writing epic documentation for shit code)
I've been spoiled by good documentation from other foss projects, like Graylog, Ansible - and versioning document frameworks like https://readthedocs.org/
Some great stuff out there, and the extra effort to put it in a decent framework if you're writing it anyway is easily outweighed by having fewer people asking how to do X or Y, because they found the answer themselves.
Thanks for the explanations. I actually use Python and R routinely, and that is also why some of this stuff seems so weird. Just a couple of quick comments:
- I did not think about field work. In that case the (by far superior) R online resources indeed will be of now help at all. Nevertheless, converting a website into a bunch of pdfs is easy, so there is no reason not to have something like https://readthedocs.org/ page for stata.
- Autocompleting variable names is very handy, and pretty much ubiquitous, there is literally no excuse not to have that.
- (Nobody uses base R alone.) Switching between windows is just a pain, unless you have several monitors, (which is probably not possible when doing field work ;) )
- If I have to select something it means either using the mouse or selecting with shift. If I want to look at the output line by line this is just A LOT of extra action.
In any case, everything I listed is just a matter of preference (but pretty much "industry standard") and will not break any workflow of old users, but will make it easier for new users to join. Especially a modern online documentation might do wonders. Saying "but what you want to do can be achieved by a workaround" is not really helpful ;) I know there is a workaround, but that is exactly the reason why it feels like I am in 1997 ;)
Well when I think of data I usually think of using python + a library, but if you have to use C++, you are going to want to find some libraries to do this. I like matplotlib (on python) but I do know it is available for C++, check this link out https://readthedocs.org/projects/matplotlib-cpp/downloads/pdf/latest/ for doing basic things like graphs. It has some sample codes. Best of luck!
I used the pushshift.io API and the reddit API to gather post scores and comments.
Netbox is a very good and complete, you got a lot of features to do whatever you want, like webhooks, it was originally meant as a source of truth, but you can do a lot with it. Ansible goes well with it, another simple tool. I like netbox-docker as well, pretty easy and fast to setup, and to manage.
Pynetbox is just a python library to interact with Netbox's API, so its very easy. I think this documentation is more than what is needed.
No, it does not have to reproduce "the documentation and/or other materials provided with the distribution". It only has to reproduce "the above copyright notice, this list of conditions and the following disclaimer " in the documentation and/or other materials provided with the distribution, i.e. not in binary distribution itself, but rather in materials coming along with distribution. Nowadays it is common practice to not include documentation into binary distribution, but just publish it online, say on https://readthedocs.org/
As much as this seems better than previous iteration (ugh), it's still quite terrible for modern standards (proportions, spacing, alignments, layout itself... list goes on, but worst offender - it's really hard to read).
Why not just use https://readthedocs.org which editing could be done by anyone through git pull requests and then approved by openSUSE team?
Right now anyone can edit wiki or add pages which results in a complete mess, it's practically useless due to either out of date or straight up harmful information.
I am working with Flask for a while now. I sure will check Sanic out to see differences in performance. You could write the docs at https://readthedocs.org/ or at least create a wiki at github if you got the time.
> how to actually find them and information about how to use their functions
For Python: https://www.python.org/doc/ https://pypi.python.org/pypi https://readthedocs.org/
> How did coders learn about the available libraries before the internet was such a wealth of knowledge
Reading the relevant Usenet and FidoNet groups and books
First off, I recommend considering a different tool that is being actively maintained if there isn't something specific to EWS that you need.
I'm not entirely sure that Dockerfile ever actually worked. It was contributed and I didn't test it before merging the PR. Even if it did work, it should only be used for testing since the resulting container has way too much going on for a thin container (DB, RabbitMQ, Nginx, EWS Application, and EWS workers running in the same container).
If you still want to try it out, I'd suggest installing it in a VM or a fat container (i.e. LXC) with an init system using the instructions here.
I like the documentation for Grav. Read the Docs also creates nice looking documentation which I have seen in many places around the web, an example of which is WTForms.
Look into https://readthedocs.org. It uses restructured text, which is very much like Markdown, but with more power.
We use git and sphinx with a custom theme for in house technical documentation. (you can theme sphinx so that it doesn't look like it's from 1996, there are themes out there or you can customize it yourself). Sphinx is lots of fun because you can do tons of stuff with it beyond generating complete html directories (like create an epub, use mathjax and typeset equations with LaTeX, etc), but it is probably overkill for most projects.
However you go about it, having some kind of version control is important and so is structuring your document in a way that allows you to sustain it. It should also be useful to the end user. which means it needs a toc, search, indices, cross referencing, etc.
I haven't worked with IRC in Python, but once you get your messages in, I think you should use SQLAlchemy to get them into your DB, this is a good talk on the topic from PyCon:
https://speakerdeck.com/pycon2014/an-introduction-to-sqlalchemy-core-by-jason-myers
For IRC, maybe you can try irc3 (https://readthedocs.org/projects/irc3/)
As a user of both Python and R, I would say the languages are different but easy to get used to one if you know the other, I would suggest going through the tutorial on python.org :
Instructions on how to install are available here:
https://github.com/yoasif/groovebasin/commit/26474c9002cc6b97a9bbc54fece2e02cfc71e91e
Soon to be available here:
https://readthedocs.org/projects/groove-basin/
Nice! It's always good to see progress on the python packaging front. It needs all the help it can get.
I don't know if you considered it or not, but you might want to look at using distlib instead of pip. Distlib is an attempt to normalize and expose packaging operations as an API. I did some work with it recently in pypicloud, and it works pretty well. It could use a bit more work, but it was way, way better than trying to use pip.