How to ReadTheDocs

•

2 recomendaciones•2,512 vistas

John Costa

DjangoMaine October Meet-up Slides for John Costa's talk on ReadTheDocs

Tecnología Educación

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

Más contenido relacionado

Similar a How to ReadTheDocs

R packages

Hadley Wickham

Rhaptos is the Plone-based open source software that powers the popular educational materials portal CNX.org which receives 1-1.6 million visitors every month from all over the world. As a very popular resource for so many people, it's imperative that the site is architected for high availability. With data centers in Houston near hurricane territory, it was critical to have a backup plan for where to host the site in the event that the data center was destroyed. This talk is a case study for how Rice University together with external consultants came up with a virtualization of the Rhaptos platform, to be able to quickly launch new instances on Amazon EC2. The deployment was completely automated for both multi-server production environments as well as one-off demo and testing instances. We'll show you how this was done and the tools and methods we used to make a rock solid solution.

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

Jazkarta, Inc.

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

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

Cohesive Networks

Docker and the Container Revolution

Romain Dorgueil

Machine learning in cybersecutiry

Vishwas N

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

rusersla

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

Ryan Koop

Engineering culture

Pamela Fox

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.

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

Kelle Cruz

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.

How OpenStack Makes Python Better (and vice-versa)

doughellmann

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

Daniel Nüst

U-Boot community analysis

xulioc

Docker training

Kiran Kumar

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

Zenoh: The Genesis

Angelo Corsaro

Docker for Fun and Profit at Startit Tech Meetup

Startit

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.

Containers for Science and High-Performance Computing

Dmitry Spodarets

Portland Science Hack Day: Open Source Hardware

Drew Fustini

LabTech Introduction

VIA Next Innovators

DockerCon 2016 Recap

Jochen Zehnder

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.

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

Codemotion

Último

Enterprise Knowledge’s Urmi Majumder, Principal Data Architecture Consultant, and Fernando Aguilar Islas, Senior Data Science Consultant, presented "Driving Behavioral Change for Information Management through Data-Driven Green Strategy" on March 27, 2024 at Enterprise Data World (EDW) in Orlando, Florida. In this presentation, Urmi and Fernando discussed a case study describing how the information management division in a large supply chain organization drove user behavior change through awareness of the carbon footprint of their duplicated and near-duplicated content, identified via advanced data analytics. Check out their presentation to gain valuable perspectives on utilizing data-driven strategies to influence positive behavioral shifts and support sustainability initiatives within your organization. In this session, participants gained answers to the following questions: - What is a Green Information Management (IM) Strategy, and why should you have one? - How can Artificial Intelligence (AI) and Machine Learning (ML) support your Green IM Strategy through content deduplication? - How can an organization use insights into their data to influence employee behavior for IM? - How can you reap additional benefits from content reduction that go beyond Green IM?

Driving Behavioral Change for Information Management through Data-Driven Gree...

Enterprise Knowledge

With more memory available, system performance of three Dell devices increased, which can translate to a better user experience Conclusion When your system has plenty of RAM to meet your needs, you can efficiently access the applications and data you need to finish projects and to-do lists without sacrificing time and focus. Our test results show that with more memory available, three Dell PCs delivered better performance and took less time to complete the Procyon Office Productivity benchmark. These advantages translate to users being able to complete workflows more quickly and multitask more easily. Whether you need the mobility of the Latitude 5440, the creative capabilities of the Precision 3470, or the high performance of the OptiPlex Tower Plus 7010, configuring your system with more RAM can help keep processes running smoothly, enabling you to do more without compromising performance.

Boost PC performance: How more available memory can improve productivity

Principled Technologies

The presentation explores the development and application of artificial intelligence (AI) from its inception to its current status in the modern world. The term "artificial intelligence" was first coined by John McCarthy in 1956 to describe efforts to develop computer programs capable of performing tasks that typically require human intelligence. This concept was first introduced at a conference held at Dartmouth College, where programs demonstrated capabilities such as playing chess, proving theorems, and interpreting texts. In the early stages, Alan Turing contributed to the field by defining intelligence as the ability of a being to respond to certain questions intelligently, proposing what is now known as the Turing Test to evaluate the presence of intelligent behavior in machines. As the decades progressed, AI evolved significantly. The 1980s focused on machine learning, teaching computers to learn from data, leading to the development of models that could improve their performance based on their experiences. The 1990s and 2000s saw further advances in algorithms and computational power, which allowed for more sophisticated data analysis techniques, including data mining. By the 2010s, the proliferation of big data and the refinement of deep learning techniques enabled AI to become mainstream. Notable milestones included the success of Google's AlphaGo and advancements in autonomous vehicles by companies like Tesla and Waymo. A major theme of the presentation is the application of generative AI, which has been used for tasks such as natural language text generation, translation, and question answering. Generative AI uses large datasets to train models that can then produce new, coherent pieces of text or other media. The presentation also discusses the ethical implications and the need for regulation in AI, highlighting issues such as privacy, bias, and the potential for misuse. These concerns have prompted calls for comprehensive regulations to ensure the safe and equitable use of AI technologies. Artificial intelligence has also played a significant role in healthcare, particularly highlighted during the COVID-19 pandemic, where it was used in drug discovery, vaccine development, and analyzing the spread of the virus. The capabilities of AI in healthcare are vast, ranging from medical diagnostics to personalized medicine, demonstrating the technology's potential to revolutionize fields beyond just technical or consumer applications. In conclusion, AI continues to be a rapidly evolving field with significant implications for various aspects of society. The development from theoretical concepts to real-world applications illustrates both the potential benefits and the challenges that come with integrating advanced technologies into everyday life. The ongoing discussion about AI ethics and regulation underscores the importance of managing these technologies responsibly to maximize their their benefits while minimizing potential harms.

Artificial Intelligence: Facts and Myths

Joaquim Jorge

How to Troubleshoot Apps for the Modern Connected Worker

ThousandEyes

How to Troubleshoot Apps for the Modern Connected Worker

ThousandEyes

In an era where artificial intelligence (AI) stands at the forefront of business innovation, Information Architecture (IA) is at the core of functionality. See “There’s No AI Without IA” – (from 2016 but even more relevant today) Understanding and leveraging how Information Architecture (IA) supports AI synergies between knowledge engineering and prompt engineering is critical for senior leaders looking to successfully deploy AI for internal and externally facing knowledge processes. This webinar be a high-level overview of the methodologies that can elevate AI-driven knowledge processes supporting both employees and customers. Core Insights Include: Strategic Knowledge Engineering: Delve into how structuring AI's knowledge base is required to prevent hallucinations, enable contextual retrieval of accurate information. This will include discussion of gold standard libraries of use cases support testing various LLMs and structures and configurations of knowledge base. Precision in Prompt Engineering: Learn the art of crafting prompts that direct AI to deliver targeted, relevant responses, thereby optimizing customer experiences and business outcomes. Unified Approach for Enhanced AI Performance: Explore the intersection of knowledge and prompt engineering to develop AI systems that are not only more responsive but also aligned with overarching business strategies. Guiding Principles for Implementation: Equip yourself with best practices, ethical guidelines, and strategic considerations for embedding these technologies into your business ecosystem effectively. This webinar is designed to empower business and technology leaders with the knowledge to harness the full potential of AI, ensuring their organizations not only keep pace with digital transformation but lead the charge. Join us to map a roadmap to fully leverage Information Architecture (IA) and AI chart a course towards a future where AI is a key pillar of strategic innovation and business success.

EIS-Webinar-Prompt-Knowledge-Eng-2024-04-08.pptx

Earley Information Science

Scaling API-first – The story of a global engineering organization

Radu Cotescu

ProductAnonymous-April2024-WinProductDiscovery-MelissaKlemke

Product Anonymous

How to convert PDF to text with Nanonets

naman860154

Boost Fertility New Invention Ups Success Rates.pdf

sudhanshuwaghmare1

Discord is a free app offering voice, video, and text chat functionalities, primarily catering to the gaming community. It serves as a hub for users to create and join servers tailored to their interests. Discord’s ecosystem comprises servers, each functioning as a distinct online community with its own channels dedicated to specific topics or activities. Users can engage in text-based discussions, voice calls, or video chats within these channels. Understanding Discord Servers Discord servers are virtual spaces where users congregate to interact, share content, and build communities. Servers may revolve around gaming, hobbies, interests, or fandoms, providing a platform for like-minded individuals to connect. Communication Features Discord offers a range of communication tools, including text channels for messaging, voice channels for real-time audio conversations, and video channels for face-to-face interactions. These features facilitate seamless communication and collaboration. What Does NSFW Mean? The acronym NSFW stands for “Not Safe For Work,” indicating content that may be inappropriate for professional or public settings. NSFW Content NSFW content encompasses material that is sexually explicit, violent, or otherwise graphic in nature. It often includes nudity, profanity, or depictions of sensitive topics.

Understanding Discord NSFW Servers A Guide for Responsible Users.pdf

UK Journal

Building Digital Trust in a Digital Economy Veronica Tan, Director - Cyber Security Agency of Singapore Apidays Singapore 2024: Connecting Customers, Business and Technology (April 17 & 18, 2024) ------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/

Apidays Singapore 2024 - Building Digital Trust in a Digital Economy by Veron...

apidays

The 7 Things I Know About Cyber Security After 25 Years | April 2024

Rafal Los

Finology Group – Insurtech Innovation Award 2024

The Digital Insurer

Strategies for Landing an Oracle DBA Job as a Fresher

Remote DBA Services

GenCyber Cyber Security Day Presentation

Michael W. Hawkins

In this session, we will delve into strategic approaches for optimizing knowledge management within Microsoft 365, amidst the evolving landscape of Copilot. From leveraging automatic metadata classification and permission governance with SharePoint Premium, to unlocking Viva Engage for the cultivation of knowledge and communities, you will gain actionable insights to bolster your organization's knowledge-sharing initiatives. In this session, we will also explore how to facilitate solutions to enable your employees to find answers and expertise within Microsoft 365. You will leave equipped with practical techniques and a deeper understanding of how there is more to effective knowledge management than just enabling Copilot, but building actual solutions to prepare the knowledge that Copilot and your employees can use.

Strategies for Unlocking Knowledge Management in Microsoft 365 in the Copilot...

Drew Madelung

As privacy and data protection regulations evolve rapidly, organizations operating in multiple jurisdictions face mounting challenges to ensure compliance and safeguard customer data. With state-specific privacy laws coming up in multiple states this year, it is essential to understand what their unique data protection regulations will require clearly. How will data privacy evolve in the US in 2024? How to stay compliant? Our panellists will guide you through the intricacies of these states' specific data privacy laws, clarifying complex legal frameworks and compliance requirements. This webinar will review: - The essential aspects of each state's privacy landscape and the latest updates - Common compliance challenges faced by organizations operating in multiple states and best practices to achieve regulatory adherence - Valuable insights into potential changes to existing regulations and prepare your organization for the evolving landscape

TrustArc Webinar - Stay Ahead of US State Data Privacy Law Developments

TrustArc

Evaluating the top large language models.pdf

ChristopherTHyatt

GenAI Risks & Security Meetup 01052024.pdf

lior mazor

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