diff --git a/doc/developers.rst b/doc/developers.rst index 3af313d96158..b78f17b2f0f8 100644 --- a/doc/developers.rst +++ b/doc/developers.rst @@ -8,6 +8,8 @@ For Developers :depth: 3 :local: +.. _pull_request: + Introduction ============ @@ -98,6 +100,14 @@ The binary releases of Drake are built with GCC 5.4 on Ubuntu 16.04 and Apple Cl The links for these packages are listed in :ref:`binary-installation`. +Issue Tracking +============== + +.. toctree:: + :maxdepth: 1 + + issues + Code Review =========== @@ -185,6 +195,42 @@ Review Process Tooling .. _continuous_integration_notes: +User Assistance +=============== + +The user-facing instructions for requesting assistance are located in +:ref:`getting_help`. The two main options for requesting assistance are either +posting a GitHub issue or a StackOverflow question. + +Handling User GitHub Issues +--------------------------- + +See :ref:`issues`. + +If a GitHub issue should instead be a StackOverflow question (e.g. it is of a +tutorial nature that does not require code or documentation modification), +please request that the user repost the question on StackOverflow, post the +new link on the GitHub issue, and close the issue. + +Handling User StackOverflow Questions +------------------------------------- + +Please subscribe to the ``drake`` tag by following +`these general instructions `_, +if you are able to. + +Please also monitor for `unanswered StackOverflow posts +`_ +once per day. If there are unanswered questions that you are unsure of the +answer, consider posting on the Slack ``#onramp`` channel to see if someone +can can look into the question. + +The following developers are subscribed to the ``drake`` tag, and will monitor +it: + + - Russ Tedrake + - Eric Cousineau + Continuous Integration Notes ============================ .. toctree:: diff --git a/doc/faq.rst b/doc/faq.rst index cffa5c18823e..24e948b20c7b 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -4,6 +4,11 @@ Frequently Asked Questions ************************** +..warning:: + + This page is old. Please review :ref:`getting_help` for more up-to-date + information. + .. contents:: `Table of contents` :depth: 3 :local: diff --git a/doc/getting_help.rst b/doc/getting_help.rst new file mode 100644 index 000000000000..570762a5f1c8 --- /dev/null +++ b/doc/getting_help.rst @@ -0,0 +1,53 @@ +.. _getting_help: + +************ +Getting Help +************ + +Searching For Your Question +=========================== + +If you need help with Drake, please first review the documentation on this +website for things such as :ref:`installation `, +`the C++ API `_, or +:ref:`Python bindings `. + +Please also briefly review +`Drake's open and closed GitHub issues `_ +and `StackOverflow posts tagged for Drake `_ +to see if your issue has been encountered by someone else before. + +Asking Your Question +==================== + +If you know your question is a bug or feature request, please +`post a GitHub issue `_. + +Otherwise, if you are seeking assistance (e.g. tutorials or a brief example), +please `post a question on StackOverflow +`_ with the ``drake`` tag. + +If you are actively developing with Drake and may need more active discussions +than what StackOverflow and GitHub may offer, consider asking for access to the +Drake Developers Slack Channel. To do so, please email Russ Tedrake for access. +Please note that this access may not always be readily granted. + +If you wish to contribute a patch, please see how to :ref:`submit a pull request +`. + +Older Sources +============= + +Some information was previously on the +:ref:`faq` +page and a +`mailing list `_. +Please do not use these resources, as they are now inactive. + +.. toctree:: + :hidden: + + faq + +.. + Use a hidden toctree to suppress error about FAQ not being linked. diff --git a/doc/index.rst b/doc/index.rst index 2efd9e0392b6..9c206ac4988a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -88,7 +88,8 @@ Here is a quick summary of capabilities: Most of these models/tools are described in `the companion textbook from an MIT course/MOOC `_. We've also recently started populating the :doc:`gallery` (contributions welcome!). -We hope you find this tool useful. Please engage us `via github issues `_ with comments, questions, success stories, and frustrations. And please contribute your best bug fixes, features, and examples! +We hope you find this tool useful. Please see :ref:`getting_help` if you wish +to share your comments, questions, success stories, or frustrations. And please contribute your best bug fixes, features, and examples! ************ @@ -122,13 +123,11 @@ Next steps :maxdepth: 1 installation - developers + getting_help Doxygen (C++) - faq - issues - Mailing list - credits GitHub + developers + credits ******************************************** diff --git a/doc/issues.rst b/doc/issues.rst index cfd4e5e9cefb..d3f632bff03d 100644 --- a/doc/issues.rst +++ b/doc/issues.rst @@ -1,3 +1,5 @@ +.. _issues: + *********************** GitHub Issue Management *********************** @@ -17,6 +19,14 @@ Please only assign labels if you are reasonably confident they are correct. The Drake development team will apply appropriate labels to issues during the weekly scrub. +Owner +===== + +All GitHub issues should have an owner. The Platform Reviewer should check once +per day that `all unassigned issues +`_ +have an appropriate owner. + Team ==== Every issue must have at least one ``team`` label. If no team agrees to own an diff --git a/doc/serve_sphinx.py b/doc/serve_sphinx.py index 5f8f05610df5..518ef2d8a18e 100644 --- a/doc/serve_sphinx.py +++ b/doc/serve_sphinx.py @@ -5,6 +5,7 @@ $ bazel run //doc:serve_sphinx """ +import argparse import os import subprocess import sys @@ -13,6 +14,19 @@ from SimpleHTTPServer import SimpleHTTPRequestHandler from SocketServer import TCPServer + +def str2bool(value): + # From: https://stackoverflow.com/a/19233287/7829525 + return value.lower() in ("yes", "y", "true", "t", "1") + + +parser = argparse.ArgumentParser() +parser.register('type', 'bool', str2bool) +parser.add_argument( + "--browser", type='bool', default=True, metavar='BOOL', + help="Open browser. Disable this if you are frequently recompiling.") +args = parser.parse_args() + # Unpack zipfile and chdir into it. with zipfile.ZipFile("doc/sphinx.zip", "r") as archive: archive.extractall("sphinx-tmp") @@ -41,11 +55,14 @@ def log_request(*_): print >>sys.stderr # Try the default browser, then wait. -print >>sys.stderr, "Opening webbrowser and waiting ... use Ctrl-C to exit." -if sys.platform == "darwin": - # macOS - webbrowser.open(http_url) -else: - # Ubuntu - webbrowser.open("./index.html") +if args.browser: + print >>sys.stderr, "Opening webbrowser" + if sys.platform == "darwin": + # macOS + webbrowser.open(http_url) + else: + # Ubuntu + webbrowser.open("./index.html") + +print >>sys.stderr, "Serving and waiting ... use Ctrl-C to exit." httpd.serve_forever()