How to ReadTheDocs

•

2 likes•2,512 views

This document discusses how to properly document code using ReadTheDocs. It recommends documenting code for reasons such as making complex code more understandable, explaining business rules, and avoiding having to re-find details. It recommends documenting dependencies, installation instructions, guides, change logs, and supported versions. The document then explains how to set up documentation on ReadTheDocs, including installing Sphinx, setting up a ReadTheDocs project, and adding a post-commit hook to automatically rebuild documentation on commits. It provides several resources for learning more about documentation best practices and ReadTheDocs.

Technology Education

How to (Really)
ReadTheDocs
https:/
/readthedocs.org/
John Costa
@johncosta

Wednesday, October 23, 13

About Me
Developer Support Engineer at DotCloud
Introduced to Python through Django when
0.96 was released.

Wednesday, October 23, 13

Overview
Documentation In General
ReadTheDocs - What is it?
ReadTheDocs - Setting up an open source
project

Wednesday, October 23, 13

Documentation
How many people document their code?

Why bother?

Wednesday, October 23, 13

Documentation
Why?
Not all code is obvious. Complex code is
complex.
Business rules may be readable, but don’t
explain why they are there.
Finding details takes a long time...it wastes
money to keep re-ﬁnding these details

Wednesday, October 23, 13

Documentation
Why?
Dependencies between systems may not be
obvious
Helps keep your project in scope (maybe) :)
Not everyone is thinking in the same context
at the same time.

Wednesday, October 23, 13

Documentation
What?
Dependencies
Installation instructions
Guides - like a readme
Things like change logs
Information about supported languages,
runtime, and tool versions

Wednesday, October 23, 13

Documentation
Where?
In a wiki?
What happens when code changes?
What if you need to support multiple
versions?
Self hosted, self managed process (script
that rebuilds documentation)

Wednesday, October 23, 13

Documentation
“Readability is a primary focus for Python
developers, in both project and code
documentation.”
- Kenneth Reitz, The Hitchhiker's Guide to
Python (python-guide)
“Documentation is communication”
- Jacob Kaplan-Moss, pycon-2011-writinggreat-documentation

Wednesday, October 23, 13

ReadTheDocs
Free(!!) hosting for Open Source documentation
Created by Eric Holscher, Charles Leifer, and
Bobby Grace for the 2010 Django Dash
Goals:
It was created to make hosting documentation
simple!
To create a central platform for people to ﬁnd
documentation (search)

Wednesday, October 23, 13

ReadTheDocs
Architecture

Wednesday, October 23, 13

Read The Docs
Documentation Start
RTD Setup
RTD Post-Commit Hook

Wednesday, October 23, 13

ReadTheDocs
Documentation Start
$ pip install sphinx
$ mkdir docs && cd docs
$ sphinx-quickstart
$ make html

Wednesday, October 23, 13

ReadTheDocs
RTD Setup

Wednesday, October 23, 13

ReadTheDocs
RTD Post-Commit Hook

Wednesday, October 23, 13

ReadTheDocs
Private RTD
Can you do it...yes!
Set it up like any other django application
stack

Or (beta)

Wednesday, October 23, 13

Things We Didn’t talk
about
Sphinx
ReStructuredText(reST)
Documentation Conventions

Wednesday, October 23, 13

Resources/References
ReStructuredText(reST):
http:/
/restructuredtext-philosophy.readthedocs.org/en/latest/
index.html
http:/
/thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html

Python Documentation Conventions
http:/
/www.python.org/dev/peps/pep-0008/#comments

Wednesday, October 23, 13

Resources/References

On Documentation:
http:/
/blip.tv/pycon-usvideos-2009-2010-2011/pycon-2011writing-great-documentation-4899042

Wednesday, October 23, 13

Resources/References
https:/
/docs.readthedocs.org/en/latest/
index.html
http:/
/programmers.stackexchange.com/
questions/121775/why-should-you-documentcode/121787
http:/
/programmers.stackexchange.com/
questions/152325/where-to-put-codedocumentation

Wednesday, October 23, 13

Resources/References
http:/
/blog.clojurewerkz.org/blog/
2013/04/20/how-to-make-your-open-sourceproject-really-awesome/
http:/
/coding.smashingmagazine.com/
2013/01/03/starting-open-source-project/
http:/
/ericholscher.com/blog/2012/jan/22/
why-read-docs-matters/

Wednesday, October 23, 13

Thank You!
@johncosta

Wednesday, October 23, 13

- The talk summarizes the history and development of Read the Docs, an open source documentation hosting platform. - It began in 2010 as a Django Dash project by Charles Leifer and Bobby Grace. Eric Holscher then developed it into a fully functional site within 48 hours. - Read the Docs allows hosting documentation from various version control systems, supports features like custom themes, full-text search, and PDF generation. It uses technologies like Git, Subdomains, Solr, Varnish, Chef, and Nginx/Gunicorn. - Being open source has provided benefits like patches, security fixes, and community contributions to help improve the project.

The story and tech of Read the Docs

ericholscher

The speaker will discuss the history and technology behind Read the Docs, an open source documentation hosting service. It started in 2010 as a Django Dash project and was built using Sphinx and reStructuredText. The site was open sourced and many popular Python projects now host their documentation on Read the Docs. The talk will cover the architecture, features like version control integration, and lessons learned around building an open source project with a large codebase and many users.

All of the Amazing OpenStack Resources

Tesora

The document introduces various OpenStack resources for users including mailing lists, IRC channels, working groups, videos, and tools. It is presented by Tyler Britten from IBM Cloud and provides an overview of basic OpenStack information sources like openstack.org as well as more specialized resources for different user groups. Contact information and links are provided for exploring OpenStack communities and getting involved with various projects.

Read the Docs: A completely open source Django project

ericholscher

Chw00t: Breaking unices’ chroot solutions

Positive Hack Days

The document discusses various techniques for breaking out of chroot jail environments on Unix-like operating systems. It begins with background information on the speaker and a brief history of chroot. It then explains what chroot is and common uses before detailing requirements for a reasonably secure chroot. The bulk of the document summarizes different techniques for escaping chroot restrictions like using classic chroot flaws, file descriptor passing, Unix domain sockets, mount, /proc, and moving directories out of the chrooted environment. It provides examples and demonstrates some techniques. It concludes by discussing future work hardening containers and operating systems against these issues.

リバースプロキシでwebサーバを集約ついでにdocker化しよう

Yasunori Kuji

This document discusses using Docker and HAProxy to set up a load balanced web server infrastructure. It demonstrates configuring two Apache web servers behind a HAProxy load balancer on a single CentOS host. The Apache containers are placed on a Docker network and configured for round-robin load balancing through the HAProxy container's ports 80 and 8001/8002 redirecting to the Apache containers.

Haskell code tools

begriffs

This document discusses various Haskell code tools that provide functionality like finding and navigating code, detecting problems, documenting code through Hoogle, and auto-formatting. It demonstrates tools like hasktags for creating a tags file for symbol definitions, codex for indexing all symbols, hscope for finding callers, hoogle for local documentation, hlint for detecting problems, stylish-haskell and hindent for formatting, and ghc-mod for autocompletion, browsing and type information. The document encourages trying these tools and contributing to haskell-vim-now, which installs Haskell development tools and configurations.

Disk forensics for the lazy and the smart

Jeff Beley

This document provides an overview of disk forensics techniques for Windows systems. It discusses retrieving data from live and offline systems, common artifacts found on disk that can reveal what executed, when, by whom and what the results were. These include Amcache, prefetch files, shellbags, master file table and more. It recommends tools for analyzing specific artifacts and demonstrates using Plaso and timeline analysis with Elastic or Splunk on disk images.

Hadley Wickham provides advice on developing R packages based on his experience creating over 20 packages. He discusses getting started with package development by choosing a name, creating directories, and adding documentation. Wickham also covers iterative development, testing packages with devtools, documenting functions and packages, and releasing packages on CRAN. He recommends learning from the source code of established packages and continuing to improve testing, namespaces, code style, and use of Git.

Scalable Plone hosting with Amazon EC2 for Rice University's Rhaptos open lea...

Jazkarta, Inc.

This document summarizes a presentation about hosting Plone on Amazon EC2 for Rice University's Rhaptos open learning platform. It discusses the benefits of cloud computing like scalability, pay-per-use pricing and disaster recovery. It then describes how to launch a Plone instance on EC2 within 5 minutes using the mr.awsome tool and buildout. Finally, it discusses how Rhaptos was hosted on EC2 for Connexions to improve disaster recovery and increase adoption.

CIW Lab with CoheisveFT: Get started in public cloud - Part 1 Cloud & Virtual...

Cohesive Networks

CohesiveFT: Get started with public cloud It's time to explore the public cloud. Get familiar with Amazon's AWS EC2 compute and S3 storage. Demo and guides will prep you to do big things with hosting for your websites and apps! Part 1 Cloud & Virtualization: Welcome! We'll run through the basics of public vs. private cloud, the cloud marketplace, and why we picked AWS to demonstrate Hosted by: Margaret Walker, Marketing Specialist

Docker and the Container Revolution

Romain Dorgueil

Machine learning in cybersecutiry

Vishwas N

This document provides an overview of machine learning in cyber security. It discusses definitions of machine learning, cyber security, and how machine learning can be used for cyber security tasks like malware detection. It also covers theoretical concepts, hands-on materials like necessary software and lab setup, and guidance for projects. Specific machine learning and security tools are mentioned, like Docker for containerization. The document aims to explain the importance and applications of machine learning in cyber security.

Los Angeles R users group - Nov 17 2010 - Part 2

rusersla

The document provides an outline for a talk on the future of R. It discusses R's current strengths and criticisms, as well as challenges like handling big data. It proposes 5 potential solutions: 1) Using R with other tools; 2) Packages for large data; 3) Improving R's capabilities; 4) Starting from scratch; 5) Adopting aspects of Clojure. Clojure is presented as having libraries for statistics, machine learning, and querying big data, positioning it as a potential model for R's evolution.

CIW Lab with CoheisveFT: Get started in public cloud - Part 1 Cloud & Virtual...

Ryan Koop

Engineering culture

Pamela Fox

The document discusses key aspects of engineering culture at companies. It notes that while college teaches technical skills, it does not teach important aspects of working at a company like code reviews, testing, documentation, and onboarding processes. A good culture values planning, writing consistent code, testing, code reviews, efficient release processes, monitoring code, and learning from mistakes through post-mortems. The document emphasizes that culture has a large impact on the work experience and success of engineering teams.

Collaborations in the Extreme:  The rise of open code development in the scie...

Kelle Cruz

Video: https://www.simonsfoundation.org/event/collaborations-in-the-extreme-the-rise-of-open-code-development-in-the-scientific-community/ The internet is changing the scientific landscape by fostering international, interdisciplinary and collaborative software development. More than ever before, software is a crucial component of any scientific result. The ability to easily share code is reshaping expectations about reproducibility -- a fundamental tenet of the scientific process. In this lecture, Kelle Cruz will briefly provide the backstory of how these shifts have come about, describe some of the most impactful open source projects, and discuss efforts currently underway aimed at ensuring these community-led projects are sustainable and receive support.

How OpenStack Makes Python Better (and vice-versa)

doughellmann

OpenStack is an open source stack that can be deployed on raw computing resources to privately or publicly present Infrastructure as a Service. It now consists of more than 4.5 million lines of code, 85% of which is Python. In this talk, Thierry Carrez and Doug Hellmann, both Python Software Foundation fellows and OpenStack Technical Committee members, look at the symbiotic relationship between OpenStack and Python. We go back in history and explain why OpenStack originally picked Python as its main language 6 years ago, and explore what does Python bring to OpenStack. We dive into examples of OpenStack pushing Python libraries to their limits and exposing new bugs. We look into the massive cloud-based continuous integration system that OpenStack uses and explain how it exposes bugs in Python libraries in the minutes after they are published to PyPI. We look into Python libraries that were created by the OpenStack community and libraries that the OpenStack community took over. Finally we'll expose a few best practices that Python developers can follow to get the most of this symbiotic relationship.

Containers for sensor web services, applications and research @ Sensor Web Co...

Daniel Nüst

U-Boot community analysis

xulioc

The document provides an outline for analyzing the U-Boot developer community. It describes the introduction, methodology, results, and conclusions sections. The methodology section discusses the tools used for the analysis including cvsanaly, mlstats, and scripts. It also covers the data sources of the U-Boot code repository, mailing list, and wiki. The results section will analyze the repository, mailing list, and perform mixed analyses.

Docker training

Kiran Kumar

This document provides an overview of Docker and containers for data science. It begins with definitions of containers and discusses the history and benefits of containers. It then explains how Docker containers work using namespaces, cgroups, and union file systems. Key Docker concepts are introduced like Dockerfiles, images, containers, and the Docker architecture. Practical examples are given for building simple machine learning models and databases in containers. Advanced topics covered include Docker Compose, DevOps workflows, continuous delivery, and Kubernetes. The document is intended to provide data scientists with an introduction to using Docker for their work.

Zenoh: The Genesis

Angelo Corsaro

This was the opening presentation of the Zenoh Summit in June 2022. The presentation goes through the motivations that lead to the design of the zenoh protocol and provides an introduction of its core concepts. This is the place to start to understand why you should care about zenoh and the way in which is disrupts existing technologies. The recording for this presentation is available at https://bit.ly/3QOuC6i

Docker for Fun and Profit at Startit Tech Meetup

Startit

Containers for Science and High-Performance Computing

Dmitry Spodarets

Within this talk, we will explore how Singularity liberates non-privileged users and host resources (such as interconnects, resource managers, file systems, accelerators, etc.) allowing users to take full control to set-up and run in their native environments. This talk explores how Singularity combines software packaging models with minimalistic containers to create very lightweight application bundles which can be simply executed and contained completely within their environment or be used to interact directly with the host file systems at native speeds. A Singularity application bundle can be as simple as containing a single binary application or as complicated as containing an entire workflow and is as flexible as you will need.

Portland Science Hack Day: Open Source Hardware

Drew Fustini

LabTech Introduction

VIA Next Innovators

This document introduces LabTech, a set of tools to help with academic research. It discusses how to search for and save academic documents, papers, source code, and LaTeX files. It also provides alternatives to common tools like Wikipedia and question/answer sites for specialized academic topics. The goal is to provide graduate students with advanced tips for efficiently finding and organizing information online to support their research.

DockerCon 2016 Recap

Jochen Zehnder

Jochen Zehnder presented a recap of DockerCon 2016. Some of the key announcements and topics covered included Docker for Mac and Windows being released as a public beta, new features in Docker 1.12 like swarm mode and built-in orchestration, and the plugin API. Experimental projects unveiled were Distributed Application Bundles and Docker for AWS/Azure. Docker Datacenter and the Docker Store were also discussed as ways to help enterprises adopt containers.

Software Heritage: let's build together the universal archive of our software...

Codemotion

Free/Open Source Software is now everywhere, but the risk of losing forever some of it is growing. Shutdowns of once popular forges are early warnings that we should not underestimate. How many million lines of code would we lose if development hubs that are hype today were to disappear 20 years from now? This talk will present Software Heritage, whose aim is to collect, preserve, and share all publicly available source code. Forever. Software Heritage has already archived 3 billion distinct source code files and 650 million commits, spanning more than 25 million development projects.

Let's Integrate MuleSoft RPA, COMPOSER, APM with AWS IDP along with Slack

shyamraj55

Uni Systems Copilot event_05062024_C.Vlachos.pdf

Uni Systems S.M.S.A.

“I’m still / I’m still / Chaining from the Block”

Claudio Di Ciccio

HCL Notes und Domino Lizenzkostenreduzierung in der Welt von DLAU

panagenda

Webinar Recording: https://www.panagenda.com/webinars/hcl-notes-und-domino-lizenzkostenreduzierung-in-der-welt-von-dlau/ DLAU und die Lizenzen nach dem CCB- und CCX-Modell sind für viele in der HCL-Community seit letztem Jahr ein heißes Thema. Als Notes- oder Domino-Kunde haben Sie vielleicht mit unerwartet hohen Benutzerzahlen und Lizenzgebühren zu kämpfen. Sie fragen sich vielleicht, wie diese neue Art der Lizenzierung funktioniert und welchen Nutzen sie Ihnen bringt. Vor allem wollen Sie sicherlich Ihr Budget einhalten und Kosten sparen, wo immer möglich. Das verstehen wir und wir möchten Ihnen dabei helfen! Wir erklären Ihnen, wie Sie häufige Konfigurationsprobleme lösen können, die dazu führen können, dass mehr Benutzer gezählt werden als nötig, und wie Sie überflüssige oder ungenutzte Konten identifizieren und entfernen können, um Geld zu sparen. Es gibt auch einige Ansätze, die zu unnötigen Ausgaben führen können, z. B. wenn ein Personendokument anstelle eines Mail-Ins für geteilte Mailboxen verwendet wird. Wir zeigen Ihnen solche Fälle und deren Lösungen. Und natürlich erklären wir Ihnen das neue Lizenzmodell. Nehmen Sie an diesem Webinar teil, bei dem HCL-Ambassador Marc Thomas und Gastredner Franz Walder Ihnen diese neue Welt näherbringen. Es vermittelt Ihnen die Tools und das Know-how, um den Überblick zu bewahren. Sie werden in der Lage sein, Ihre Kosten durch eine optimierte Domino-Konfiguration zu reduzieren und auch in Zukunft gering zu halten. Diese Themen werden behandelt - Reduzierung der Lizenzkosten durch Auffinden und Beheben von Fehlkonfigurationen und überflüssigen Konten - Wie funktionieren CCB- und CCX-Lizenzen wirklich? - Verstehen des DLAU-Tools und wie man es am besten nutzt - Tipps für häufige Problembereiche, wie z. B. Team-Postfächer, Funktions-/Testbenutzer usw. - Praxisbeispiele und Best Practices zum sofortigen Umsetzen

Presentation of the OECD Artificial Intelligence Review of Germany

innovationoecd

Infrastructure Challenges in Scaling RAG with Custom AI models

Zilliz

Building Retrieval-Augmented Generation (RAG) systems with open-source and custom AI models is a complex task. This talk explores the challenges in productionizing RAG systems, including retrieval performance, response synthesis, and evaluation. We’ll discuss how to leverage open-source models like text embeddings, language models, and custom fine-tuned models to enhance RAG performance. Additionally, we’ll cover how BentoML can help orchestrate and scale these AI components efficiently, ensuring seamless deployment and management of RAG systems in the cloud.

Pushing the limits of ePRTC: 100ns holdover for 100 days

Adtran

GraphSummit Singapore | The Art of the Possible with Graph - Q2 2024

Neo4j

Serial Arm Control in Real Time Presentation

tolgahangng

Recently uploaded (20)

Let's Integrate MuleSoft RPA, COMPOSER, APM with AWS IDP along with Slack

Uni Systems Copilot event_05062024_C.Vlachos.pdf

Essentials of Automations: The Art of Triggers and Actions in FME

Unlock the Future of Search with MongoDB Atlas_ Vector Search Unleashed.pdf

20240609 QFM020 Irresponsible AI Reading List May 2024

HCL Notes and Domino License Cost Reduction in the World of DLAU

Cosa hanno in comune un mattoncino Lego e la backdoor XZ?

Climate Impact of Software Testing at Nordic Testing Days

TrustArc Webinar - 2024 Global Privacy Survey

GenAI Pilot Implementation in the organizations

UiPath Test Automation using UiPath Test Suite series, part 5

Mind map of terminologies used in context of Generative AI

20240607 QFM018 Elixir Reading List May 2024

“I’m still / I’m still / Chaining from the Block”

HCL Notes und Domino Lizenzkostenreduzierung in der Welt von DLAU

Presentation of the OECD Artificial Intelligence Review of Germany

Infrastructure Challenges in Scaling RAG with Custom AI models

Pushing the limits of ePRTC: 100ns holdover for 100 days

GraphSummit Singapore | The Art of the Possible with Graph - Q2 2024

Serial Arm Control in Real Time Presentation

How to ReadTheDocs

1. How to (Really) ReadTheDocs https:/ /readthedocs.org/ John Costa @johncosta Wednesday, October 23, 13

2. About Me Developer Support Engineer at DotCloud Introduced to Python through Django when 0.96 was released. Wednesday, October 23, 13

3. Overview Documentation In General ReadTheDocs - What is it? ReadTheDocs - Setting up an open source project Wednesday, October 23, 13

4. Documentation How many people document their code? Why bother? Wednesday, October 23, 13

5. Documentation Why? Not all code is obvious. Complex code is complex. Business rules may be readable, but don’t explain why they are there. Finding details takes a long time...it wastes money to keep re-ﬁnding these details Wednesday, October 23, 13

6. Documentation Why? Dependencies between systems may not be obvious Helps keep your project in scope (maybe) :) Not everyone is thinking in the same context at the same time. Wednesday, October 23, 13

7. Documentation What? Dependencies Installation instructions Guides - like a readme Things like change logs Information about supported languages, runtime, and tool versions Wednesday, October 23, 13

8. Documentation Where? In a wiki? What happens when code changes? What if you need to support multiple versions? Self hosted, self managed process (script that rebuilds documentation) Wednesday, October 23, 13

9. Documentation “Readability is a primary focus for Python developers, in both project and code documentation.” - Kenneth Reitz, The Hitchhiker's Guide to Python (python-guide) “Documentation is communication” - Jacob Kaplan-Moss, pycon-2011-writinggreat-documentation Wednesday, October 23, 13

10. ReadTheDocs Free(!!) hosting for Open Source documentation Created by Eric Holscher, Charles Leifer, and Bobby Grace for the 2010 Django Dash Goals: It was created to make hosting documentation simple! To create a central platform for people to ﬁnd documentation (search) Wednesday, October 23, 13

11. ReadTheDocs Architecture Wednesday, October 23, 13

12. Read The Docs Documentation Start RTD Setup RTD Post-Commit Hook Wednesday, October 23, 13

13. ReadTheDocs Documentation Start $ pip install sphinx $ mkdir docs && cd docs $ sphinx-quickstart $ make html Wednesday, October 23, 13

14. ReadTheDocs RTD Setup Wednesday, October 23, 13

15. ReadTheDocs RTD Setup Wednesday, October 23, 13

16. ReadTheDocs RTD Setup Wednesday, October 23, 13

17. ReadTheDocs RTD Post-Commit Hook Wednesday, October 23, 13

18. ReadTheDocs RTD Post-Commit Hook Wednesday, October 23, 13

19. ReadTheDocs RTD Post-Commit Hook Wednesday, October 23, 13

20. ReadTheDocs Private RTD Can you do it...yes! Set it up like any other django application stack Or (beta) Wednesday, October 23, 13

21. Things We Didn’t talk about Sphinx ReStructuredText(reST) Documentation Conventions Wednesday, October 23, 13

22. Resources/References ReStructuredText(reST): http:/ /restructuredtext-philosophy.readthedocs.org/en/latest/ index.html http:/ /thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html Python Documentation Conventions http:/ /www.python.org/dev/peps/pep-0008/#comments Wednesday, October 23, 13