Python read the docs

Python read the docs DEFAULT

Welcome to Read the Docs

build statusDocumentation StatusTest coverage

Purpose

Read the Docs hosts documentation for the open source community. It supports Sphinx docs written with reStructuredText, and can pull from your Subversion, Bazaar, Git, and Mercurial repositories. Then we build documentation and host it for you. Think of it as Continuous Documentation.

Documentation for RTD

You will find complete documentation for setting up your project at the Read the Docs site.

Get in touch

You can find information about getting in touch with Read the Docs at our Contribution page.

Contributing

You can find information about contributing to Read the Docs at our Contribution page.

Quickstart for GitHub-Hosted Projects

By the end of this quickstart, you will have a new project automatically updated when you push to GitHub.

  1. Create an account on Read the Docs. You will get an email verifying your email address which you should accept within 7 days.
  2. Log in and click on "Import a Project".
  3. Click "Connect to GitHub" in order to connect your account's repositories to GitHub.
  4. When prompted on GitHub, give access to your account.
  5. Click "Import a Repository" and select any desired repository.
  6. Change any information if desired and click "Next".
  7. All done. Commit away and your project will auto-update.

License

MIT © 2010-2021 Read the Docs, Inc. & contributors

Sours: https://github.com/readthedocs/readthedocs.org

The source code that powers readthedocs.org

Update django-filter from 2.4.0 to 21.1.

Update drf-flex-fields from 0.9.3 to 0.9.4.

The bot wasn't able to find a changelog for this release. Got an idea?

Update elasticsearch from 7.14.1 to 7.15.0.

Update selectolax from 0.3.2 to 0.3.4.

Update pytz from 2021.1 to 2021.3.

The bot wasn't able to find a changelog for this release. Got an idea?

Update regex from 2021.8.28 to 2021.9.30.

The bot wasn't able to find a changelog for this release. Got an idea?

Update django-crispy-forms from 1.12.0 to 1.13.0.

Update nltk from 3.6.3 to 3.6.4.

Update django-permissions-policy from 4.2.0 to 4.3.0.

The bot wasn't able to find a changelog for this release. Got an idea?

Update watchdog from 2.1.5 to 2.1.6.

Update awscli from 1.20.48 to 1.20.53.

Update django-dynamic-fixture from 3.1.1 to 3.1.2.

The bot wasn't able to find a changelog for this release. Got an idea?

Update pytest-cov from 2.12.1 to 3.0.0.

Sours: https://pythonrepo.com/repo/readthedocs-readthedocs-org-python-documentation
  1. Rhode island snow storm update
  2. Adobe illustrator download
  3. Gujarati movie youtube
  4. Bmw bilstein shocks

Read the Docs: Documentation Simplified¶

Read the Docs simplifies software documentation by building, versioning, and hosting of your docs, automatically. Think of it as Continuous Documentation.

Never out of sync 🔄

Whenever you push code to your favorite version control system, whether that is Git, Mercurial, Bazaar, or Subversion, Read the Docs will automatically build your docs so your code and documentation are always up-to-date. Read more about Incoming Webhooks and Automation.

Multiple versions 🗂️

Read the Docs can host and build multiple versions of your docs so having a 1.0 version of your docs and a 2.0 version of your docs is as easy as having a separate branch or tag in your version control system. Read more about Versioned Documentation.

Open Source and User Focused 💓

Our code is free and open source. Our company is bootstrapped and 100% user focused. Read the Docs Community hosts documentation for over 100,000 large and small open source projects, in almost every human and computer language. Read the Docs for Business supports hundreds of organizations with product and internal documentation.

You can find out more about our all the Read the Docs features in these pages.

First steps¶

Are you new to software documentation or are you looking to use your existing docs with Read the Docs? Learn about documentation authoring tools such as Sphinx and MkDocs to help you create fantastic documentation for your project.

Read the Docs feature overview¶

Learn more about configuring your automated documentation builds and some of the core features of Read the Docs.

How-to Guides¶

These guides will help walk you through specific use cases related to Read the Docs itself, documentation tools like Sphinx and MkDocs and how to write successful documentation.

Advanced features of Read the Docs¶

Read the Docs offers many advanced features and options. Learn more about these integrations and how you can get the most out of your documentation and Read the Docs.

The Read the Docs project and organization¶

Learn about Read the Docs, the project and the company, and find out how you can get involved and contribute to the development and success of Read the Docs and the larger software documentation ecosystem.


© Copyright 2010-2021, Read the Docs, Inc & contributors. Revision .

Built with Sphinx using a theme provided by Read the Docs.
Sours: https://docs.readthedocs.io/
Python Basics: Documentation

Docstrings are not included in Read the Docs Sphinx build

Remember that Sphinx's Autodoc extension "imports the modules to be documented". That's because Autodoc uses Python introspection to access the doc-strings. This has the advantage, from Autodoc's perspective, that it can let Python do the parsing. The disadvantage, from a user perspective, is that we have to make sure all dependencies are installed, or at least "mocked".

This is not a problem on your development machine where, naturally, all external libraries your package depends on are already installed. But when building on the Read-the-Docs server, in a "naked" Python environment so to speak, many of them are missing. You added the dependencies required for building the Sphinx project to , and that would be sufficient if you didn't use the Autodoc extension. But since you do, your doc-strings are missing because modules in your package import something like or . On Read-the-Docs, you should see warning messages to that effect if you look at the extended log (not the basic one you posted), which is accessible by clicking "View raw" in the Builds tab. These are warnings, not errors. So the build passes, but the doc-strings are missing.

Adding the extra dependencies will slow down the documentation builds because they all have to be installed before Sphinx even gets to work. So a better strategy is to mock them. You can test that locally as well.

Packages which are imported like can be mocked by adding the Autodoc option to :

If you import objects directly from a package's name space, like , it may be necessary to use from the module instead:

Sours: https://stackoverflow.com/questions/67485175/docstrings-are-not-included-in-read-the-docs-sphinx-build

Docs the python read

Technical documentation lives here

Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you.

Free docs hosting for open source

We will host your documentation for free, forever. There are no tricks. We help over 100,000 open source projects share their docs, including a custom domain and theme.

Always up to date

Whenever you push code to your favorite version control service, whether that is GitHub, BitBucket, or GitLab, we will automatically build your docs so your code and documentation are never out of sync.

Downloadable formats

We build and host your docs for the web, but they are also viewable as PDFs, as single page HTML, and for eReaders. No additional configuration is required.

Multiple versions

We can host and build multiple versions of your docs so having a 1.0 version of your docs and a 2.0 version of your docs is as easy as having a separate branch or tag in your version control system.

Read the Tutorial

Search all the docs

About Read the Docs

Read the Docs has grown substantially since its beginning as a weekend project and is closing in on being a top-1000 site on the internet. Today, we:

  • Serve over 55 million pages of documentation a month
  • Serve over 40 TB of documentation a month
  • Host over 80,000 open source projects and support over 100,000 users
  • Are supported by a very small team of dedicated engineers

Read the Docs is funded by the community

We fund our operations through advertising, corporate-hosted documentation with Read the Docs for Business, donations, and we are supported by a number of generous sponsors.

Read the Docs is open source and community supported. It depends on users like you to contribute to development, support, and operations. You can learn more about how to contribute in our docs. Thanks so much to our wonderful team who helps us run the site. Read the Docs wouldn't be possible without them.

Hosting for the project is graciously provided by AWS and Cloudflare.

Sours: https://readthedocs.org/
Live Coding: Documentation w/ rentapunto.com (RTFD)

How to Set Up Your Python Project Docs for Success 🎉

If you don’t have a basic working Python package, check out my guide to making one here. Then read the next article to learn how to add tests, Travis, Coveralls, Black, and PyUp so that you have more faith your code won’t break.

The example project I’ll use in this article is pybraries, a wrapper I made for the libraries.io API. You can use it to subscribe to email alerts for new versions of open source packages. You can also use it to find information about many aspects of open source packages and repositories. Here are the docs. Let’s see how to build them! 🚀

Read the Docs (RTD) hosts open source project docs for free! It’s very cool. 🕶

Set up your Read the Docs account at https://readthedocs.org.

Then do the following:

  1. Import your GitHub repository manually if you don’t see it listed as available to access on RTD.
  2. Once you are in your project on RTD, enter the relevant information and check the box for Edit advanced project options.
  3. On the next screen choose Python for your Programming Language.
  4. Click Finish. Then Admin. Then Advanced Settings.
  5. Check the box for Install your project inside a virtualenv using setup.py install and enter in the Requirementsfile field (assuming that’s the name of your requirements file. Save. Alternatively, you can create a readthedocs.yml configuration file as explained here.
settings
settings

6. Click on the Builds tab. You should see that a build is in progress or completed.

7. When the build is completed, click on View Docs. These docs aren’t showing much info specific to our package yet — we’ll work on that in a moment.

When you push to GitHub your docs will build automatically if a webhoook is configured. If you automatically connected your repo to GitHub, you may not need to configure anything else for auto-builds. ☝️

If you manually imported your repo, you’ll need to set up a webhook. Instructions can be found here. I made minor improvements to these docs, so if you think something is unclear, improve them with a PR. 😄 Here’s how to add a webhook:

In your GitHub repo, go to Settings -> Webhooks -> Add webhook. You should see a form like the one below.

add webhook screenshot
add webhook screenshot

For Payload URL, go to RTD’s Integrations settingand copy the webhook information. Prepend it with . You can leave everything else alone and click Add webhook. Or choose Let me select individual events if you want to trigger RTD doc builds in response to other GitHub events beyond pushes to the repo. FYI, I had to delete my webhook on RTD and GitHub and redo re-add the webhook to make it work.

Next time you push your code to GitHub and merge the PR, head to RTD. You should see that your docs were rebuilt automatically! 🎉 Give it a few minutes if you don’t see changes right away.

build history on RTD
build history on RTD

Cool! Now let’s set up Sphinx to generate our documents for RTD.

Sphinx claims to make it easy to create intelligent and beautiful Python documents. I don’t know that I’d say it’s a snap, but Sphinx is pretty cool. 😉 Features include syntax highlighting, themes, and easy document linking. Here’s the Sphinx getting started guide for reference.

Add to requirements_dev.txt and install it with .

Create a docs directory in the top level of your project directory. In that directory, run from the command line.

You will be asked a few questions. Enter the project name and author name when prompted. Generally the defaults are what you want.

The following files will be generated automatically:

conf.py

conf.py controls how Sphinx runs when the docs are built. In it, you configure project documentation settings. Let’s make a few changes to conf.py to make Sphinx create better docs. Uncomment and adjust the section so the abspath is

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Insert the following into the list of extensions:

extensions = [
'sphinx.ext.napoleon',
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.coverage',
]

I’m not a fan of the alabaster template, so I added to my requirement_dev.py file and installed it.

If you do the same thing, change the line about html_theme in conf.py to this:

html_theme = ‘sphinx_rtd_theme’

Make

Make is a build automation tool. The Makefile that was generated by Sphinx controls how shortcut commands that start with operate. Learn more about makefiles here. You can probably get by without digging deeply into Make. 😉

Run from the command line to create your docs with this one shortcut command. Then, in your docs->build_->html directory you should see index.html. Open the file in your browser and you should see your bare-bones docs. 😄

To check for any undocumented functions and classes, add the following lines to your Makefile.

%: Makefile
@$(SPHINXBUILD) -M [email protected] "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@$(SPHINXBUILD) -M [email protected] "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -b coverage

The line appended creates a coverage report so that can tell you how much of your code is documented. Now when you run , the html folder will contain a text file named python.txt. That will show you where you need some documentation. 😀

Commit and continue on to make your doc files.

You can choose whether to write your files in Markdown (hereinafter md) or reStructuredText (hereinafter rst). Md is closer to regular prose and faster to learn. However, rst allows you to use more of Sphinx’s powerful features. Here’s the GitHub guide to md and here’s the Sphinx guide to rst.

It’s your choice whether to invest the time in learning rst. There are about a billion other things you could learn, so if it isn’t at the top of your list, I get it. 😉 However, many project’s docs are written in rst, so it’s nice to know.

You can convert between snippets of md and rst quickly with this online pandoc converter. You can use it to copy-paste from one format to the other. CloudConvert does the same with whole files. CloudConvert starts charging after 25 minutes of use per day. ☝️

If you are going the rst route, switch your README file extension to .rst.

Also, setup.py will need the README name and long_description_content_type switched to rst.

I’m going to use rst. If you’re using md, change the file extensions below to .md.

Create the following files:

  1. CODE_OF_CONDUCT.rst
  2. CONTRIBUTING.rst
  3. HISTORY.rst
  4. README.rst

CODE_OF_CONDUCT.rst

Here’s GitHub info with a template code of conduct. The code of conduct explains how folks are expected to conduct themselves with regard to collaborating on your project and what to do if individuals are not acting appropriately. Add your email where the template has a place for it. If you want to copy the GitHub markdown template into rst, you can use one of the converters mentioned above. 😀

CONTRIBUTING.rst

Make it easy for people who want to contribute to your project to do so. Put clear instructions in your contributing file. Feel free to use my file as a base.

HISTORY.rst

History will contain your changelog. It is helpful for package users. You can also use the contents in your release info on GitHub. ☝️

In history.rst add the following.

=======
History
=======0.0.1 (2020–05–15)
— — — — — — — — -* First release on PyPI.

Update the date to the appropriate date and add any other relevant bullet points. You’ll append the file as you make release new versions of your package.

README.rst

Your README should include install and basic use information. I suggest you point users to the full docs on RTD. 👉

You can add other documents to your project, but make sure you put the file names in your index.rst’s TOC. Then they will show up and be linked to in your built docs. 😀

Now let’s make sure our users can get help understanding what your functions and classes do.

papers stacked
papers stacked

Docstrings are a method of communicating to your user how a class or function works. The docstrings will show up in your users’s code when they ask for help. Sphinx will take your docstrings and automatically make them usable in your docs on RTD, too. 👍

Write your Docstrings in your code, immediately after the first line of your class or function. Docstrings start with triple quotes and should include any info your user might need, including information about parameters and return values.

Python doesn’t have one obvious way to format docstrings. Pick one way to write docstrings so they look neat and no one has to ask or think about how to do things. 😀

I suggest using Google style — which is recommended for ease of writing and reading. A good discussion of docstring formatting can be found here.

Make sure you let your contributors know about your chosen docstring format by including instructions in your contributing file. ☝️

When you have docstrings in you code, you can then build your docs locally and see your docstrings in your browser. When the local version looks good, commit, push, and merge your PR to see your docstrings on RTD at your module page.

If things don’t work as expected, here are some suggestions to get you back on track:

Troubleshooting

Sphinx and RTD can break or cause docs to look different than expected for many reasons. Check the build logs in RTD to find errors.

Common problems include:

  • If you docs are not building and you are using rst files, there is likely invalid rst somewhere. To find invalid rst, run file contents through one of the rst checkers mentioned above.
  • If your docs build but your modules aren’t displaying, check the raw output logs on RTD for hints.
  • Make sure your setup.py and requirements_dev.txt files are correct.
  • If you need an environment variable for things to run add it in the RTD settings.

The RTD and Sphinx docs and Stack Overflow are helpful, but I’ve found this troubleshooting cumbersome. I feel your pain. 🙁

Now let’s look at a nicer topic — communicating information to prospective users via badges.

Badges provide at-a-glance information to people interested in your project. Badges can instill confidence and legitimacy. Here’s an example of the badges that can sit atop your README:

badges
badges

Many badges are available at https://shields.io/ and https://badgen.net/. I added some of mine from shields.io. To get the badge code, don’t just copy the url next to the badge. Click on the URL. Then append your package name. See the example below for the wheel badge.

badging screenshot
badging screenshot

Then copy the md or rst code from the dropdown and paste it into your README.

Many badges are available at the website of the relevant app. PyUp, Travis, and Coveralls have badge code you can grab. For PyUp, if you click on the badge on your PyUp dashboard, you’ll then see the code you can copy and embed in your README.

pyup badge code
pyup badge code

Here’s RTD’s info on badges.

Cool! We’re badged. Finally, let’s look at facilitating collaboration.

Help from the larger community is a great benefit available to an open source project. You want to make it easy for your users to report bugs and feature requests with relevant information. A great first step is providing a clear issue template.

Issue Templates

In your browser, go to your GitHub repo ->Settings -> Options. Under Features, click the Green Set up templates button.

screenshot of set up issue templates
screenshot of set up issue templates

You can add a custom issue template or use one of the default templates from GitHub.

Pull request templates are similarly helpful. GitHub has a good guide to making one here.

Now it’ll be easier for your to get help with your open source project!

In this article you learned how to make great docs that build automatically. You learned how to convey information at a glance with badges, too. Finally, you saw how you can make attract collaborators.

Now people will know how to use and contribute to your package. Awesome! 🎉

I hope you found this guide useful. If you did, please share it on your favorite social media channels so others can find it too. 👍

I write about Python, Docker, data science, and other tech topics. If any of that’s of interest to you subscribe to my Data Awesome mailing list and read more here. 😀

Sours: https://towardsdatascience.com/how-to-set-up-your-python-project-docs-for-success-aab613f79626

You will also like:

Repositories

  • blog Public

    Read the Docs blog

    CSS 13 35 2 4 Updated

  • ethicalads.io Public

    This repository contains the public marketing website for EthicalAds. The ad server is in the ethical-ad-server repository.

    CSS 9 21 0 5 Updated

  • ethical-ad-server Public

    The ethical ad server - ads for developers without all the tracking

    Python 58 AGPL-3.0 24 13 2 Updated

  • sphinx-hoverxref Public

    Tooltip with content embedded when hover an internal reference

    Python 40 MIT 25 19 4 Updated

You can’t perform that action at this time.

You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.

Sours: https://github.com/readthedocs


109 110 111 112 113