[WIP] Streamline docbuild

[willingc]

Addresses #215

This is still a WIP but it restructures the doc build for Circuitpython to minimize warnings and allow local builds to follow a more standard workflow.

Current rendering: http://test-circuitpython.readthedocs.io/en/streamline-docbuild/

• Local build is now down to 9 warnings.
• make linkcheck now only warns on 1 link
• split doc source into CircuitPython and MP

This is currently only the HTML doc version, will add epub and LateX back.

Please review the current rendering for any missing content. @danhalbert If you could do a quick skim of the docs with your eagle eyes, I would appreciate it. Thanks.

To do:

• Correct Core Modules/Modules section
• Correct Supported Ports/Atmel SAMD/Port specific modules
• Correct Supported Ports/SAMD/Port specific modules
• Edit doc footer
• Edit sidebar footer selector and GitHub link
• Update version in conf.py

[tannewt]

Thanks for taking this on Carol! ESP8266 is also a supported port but we haven't put much polish on its APIs (and therefore the docs) yet. I can also get you a blinka without a background for the logo. Let me know when I should take a closer look.

Also, sorry for Rosie CI disliking you. I'll keep poking it.

[dhalbert]

Hi @willingc Thanks as well! I will make a copy-editing pass at some point, after the structure as stabilized.

How do (and @tannewt , you too) you envision our doc tree meshing with MicroPython's? Or will we not. If you go to http://docs.micropython.org/en/latest/pyboard/index.html, which is the standard top of the tree, there's a bunch of pyboard-specific stuff which we'd obviously omit, and then there are these sections:

• MicroPython libraries
• The MicroPython language
• MicroPython differences from CPython
• MicroPython License Information

There's information in those sections that's obviously useful to CPy users, but some of it is different in CPy from MPy. The text also refers to "MicroPython" everywhere, of course. Should we s/MicroPython/CircuitPython/ everywhere, change what's different (e.g. uos vs os) and refix these when we merge again from upstream?

[KurticusMaximus]

You guys are reading my mind. I was just going to ask about this.

[dhalbert]

Individual comments:
http://test-circuitpython.readthedocs.io/en/streamline-docbuild/shared_bindings_index.html
Support Matrix should have links in the module names and the ports could link to some entry for each port as well.
http://test-circuitpython.readthedocs.io/en/streamline-docbuild/README_cp_doc.html
"Adafruit’s CircuitPython Documentation" is meta-documentation. I first clicked here and thought I might see, say, library. So I think the top-level title should be clearer about what's inside.

[willingc]

Good questions @dhalbert. I will leave it to you, Scott, and the rest of the Adafruit team to determine the strategy re: Micropython docs.

My two cents:

• I think @tdicola is on the right track with the programming guide. It's self contained yet can be served with the existing docs.
• I would create separation between the CP docs and the MP docs. The current MP build process is far from standard for Sphinx and will be difficult to maintain over time. For docs, you really want the build process parameters to be in the docs directory instead of the repo root.
• I would leave the MP docs as is (i.e. not change the naming to CP) but instead adapt the CP docs to refer to CP content unless the MP is needed.
• Although it's nice to have the docs in the same repo, it may be helpful to create a docs repo and include the MP content as a git submodule. This may make updates to MP releases simpler.

[willingc]

"Adafruit’s CircuitPython Documentation" is meta-documentation. I first clicked here and thought I might see, say, library. So I think the top-level title should be clearer about what's inside.

Good point @dhalbert. I will change the title to reflect that its how to build the docs themselves.

[tannewt]

I'm not particularly wedded to the MicroPython docs. Most of them seem very board specific or advanced. So, for docs I say we remove most of them. However, we can use intersphinx to link out to pages that we do want to point people to.

@willingc could you elaborate on the standard sphinx build process? I'm wondering if I've set it up correctly in our cookiecutter repo for libraries.

[willingc]

@tannewt Sounds good to me.

Here's a link to a repo that has a reasonable doc structure which we can use for a cookiecutter https://github.com/willingc/doc-basics 😄

[tannewt]

How do you suggest structuring it when docs are extracted from code? CircuitPython does it with sed from c and the libraries use autodoc.

…

On Sun, Sep 10, 2017 at 6:00 PM Carol Willing ***@***.***> wrote: @tannewt <https://github.com/tannewt> Sounds good to me. Here's a link to a repo that has a reasonable doc structure which we can use for a cookiecutter https://github.com/willingc/doc-basics 😄 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#244 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AADNqZA61CA1gBfB4TLljz96U1C-YgMSks5shIYkgaJpZM4PPFNf> .

[willingc]

@tannewt I would structure it similarly. I would likely move the c2rst code that does parsing into a custom Sphinx extension. Autodoc can be used as it is now (we would just have to adjust a couple of conf.py lines).

Since this PR is slated for 3.0, let me take some time when I am able to write the extension and see where that puts us. The nice thing if we can get the build simplified is it opens up the option for moving/editing docs more easily. ☀️

[tannewt]

Beginners please check out the newest version of these docs and provide feedback here!

[tannewt]

@willingc or someone else please reopen this when its closer to needing a review.

[willingc]

Thanks @tannewt. Will do. Hope all is well with you too.