> the talk I gave last month at PyOhio ( https://www.pyohio.org/2019/presentations/137)
> Right now I have the slides up as a view-only share in my Google Drive ( bit.ly/bskinn-pyohio2019-intersphinx). Perhaps it would be useful to link to them? Or, to host a PDF someplace more permanent, and link to that? Thanks for the links, I'll definitely take a look through them for myself to see if I can gain any additional information. I've been using Sphinx and reST a decent amount recently, but I'm definitely not the most experienced. Also, there's a PR open for providing netlify previews for CPython PRs: https://github.com/python/cpython/pull/15288. From what I understand, we'll be recommending for PR authors to use that to preview documentation changes, particularly when any rich formatting is involved. > - [ ] And a *link*/"reference" from the "extensive cross-references" paragraph of https://www.sphinx-doc.org/en/master/ to the cross-referencing docs We currently link to the Sphinx docs in the dedicated section, "Additional Markup Constructs": https://devguide.python.org/documenting/#additional-markup-constructs. The section in the PR was only meant to provide a very brief summary for using Sphinx in NEWS entries. I included a link to the "Additional Markup Constructs" section for readers looking for additional information. It might be worthwhile to create a new subsection for links to external resources and guides. If accepted, the best location in the devguide would probably be 7.4.12 (assuming that no other sections are added in the meantime). However, that proposal would have to be in it's own topic, rather than in this one. On Mon, Aug 19, 2019 at 12:33 PM Wes Turner <wes.tur...@gmail.com> wrote: > - [ ] A page or section in the Sphinx docs would be helpful for many, I > think > > https://github.com/sphinx-doc/sphinx/tree/master/doc > > `<https://github.com/sphinx-doc/sphinx/tree/master/doc>`__ > > > .. index:: Implicit reference > .. _implicit-reference: > > Implicit ref > ------------------- > > `implicit ref`_ > > `anchor text <implicit ref>`_ > > `implicit-reference`_ > > `implicit reference`_ > > :func:`modname.funcname` > > :meth:`modname.Classname.methname` > > :class:`modname.Classname` > > And, FWIW: > > :cite:`cpython37` > > .. bibliography:: references.bib > > References.bib > -------------------------- > .. code:: latex > > @techreport{cpython37, > title="Python 3.7 Documentation", > author="Python Software Foundation", > year=1999, > howpublished = "\url{https://docs.python.org/3.7/}";, > } > > > > - [ ] And/Or examples on the roles docs page > https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role > > - [ ] And a *link*/"reference" from the "extensive cross-references" > paragraph of https://www.sphinx-doc.org/en/master/ to the > cross-referencing docs > > - [ ] And how to do parenthetical citations of / reference CPython with > e.g. bibtex [with the `.. bibliography::` directive and :cite:`refkey` role > from sphinxcontrib-bibtex] > > There are lots of great Sphinx primers; awesome-sphinxdoc could link to > them to help everyone: > https://github.com/yoloseem/awesome-sphinxdoc > > On Monday, August 19, 2019, <brian.sk...@gmail.com> wrote: > >> Citing from the current (19 Aug 2019) version of this PR ( >> https://github.com/python/devguide/pull/525/files#diff-50cb76bbe8ae3fcd4170dc6e8d9d6b3fR225-R226 >> ): >> >> > Before using any Sphinx roles, ensure that a corresponding entry exists >> within the documentation. >> >> At the risk of crass self-promotion, the talk I gave last month at PyOhio >> (https://www.pyohio.org/2019/presentations/137) provides step-by-step >> instructions for how to find the information needed to craft a working >> Sphinx cross-reference, along with some of the tooling that's available. >> >> Right now I have the slides up as a view-only share in my Google Drive ( >> bit.ly/bskinn-pyohio2019-intersphinx). Perhaps it would be useful to >> link to them? Or, to host a PDF someplace more permanent, and link to that? >> _______________________________________________ >> Python-Dev mailing list -- python-dev@python.org >> To unsubscribe send an email to python-dev-le...@python.org >> https://mail.python.org/mailman3/lists/python-dev.python.org/ >> Message archived at >> https://mail.python.org/archives/list/python-dev@python.org/message/IK5XP7CPZDF2FSFG55JRKXHEXNTOMUTB/ >> > _______________________________________________ > Python-Dev mailing list -- python-dev@python.org > To unsubscribe send an email to python-dev-le...@python.org > https://mail.python.org/mailman3/lists/python-dev.python.org/ > Message archived at > https://mail.python.org/archives/list/python-dev@python.org/message/SSMNWK7YF6WRT2NO4C2IQ6PGD2XVJOZT/ >
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/W2SPJKB33B6XSKOUJFYEFZZTZQ7ZX6EX/
