From 39b9fc105fcc9c2b9525ad435596f46a31f74b70 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Tue, 10 May 2022 20:54:52 +0100 Subject: [PATCH 1/3] add doctest-skip and inline code example --- doc/contributing.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/doc/contributing.md b/doc/contributing.md index d29d6391b87..b174c8cfa5c 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -315,6 +315,25 @@ This will build the HTML files in `doc/_build/html`. Open `doc/_build/html/index.html` in your browser to view the pages. Follow the [pull request workflow](contributing.md#pull-request-workflow) to submit your changes for review. +### Adding example code + +Many of the PyGMT functions have example code in their documentation. To contribute an example, add an "Example header" +and put the example code below it. Have all lines begin with ">>>". To keep this example code from being run during +testing, add the code "__doctest_skip__ = [function name]" to the top of the module. + +**Inline code example** + +`` +__doctest_skip__ = ["module_name"] +`` + + Example + ------- + >>> import pygmt + >>> # Comment describing what is happening + >>> Code example + + ### Contributing Gallery Plots The gallery and tutorials are managed by From 3aa5608edc0fc102a6ec12582857399ad1addde0 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Tue, 10 May 2022 20:55:50 +0100 Subject: [PATCH 2/3] add explanation --- doc/contributing.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/contributing.md b/doc/contributing.md index b174c8cfa5c..b341fa739ad 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -323,10 +323,14 @@ testing, add the code "__doctest_skip__ = [function name]" to the top of the mod **Inline code example** +Below the import statements at the top of the file + `` __doctest_skip__ = ["module_name"] `` +At the end of the function's docstring + Example ------- >>> import pygmt From a4c894a2cb1202e2c506cca2bfebcc3cbc3f8174 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Tue, 31 May 2022 06:14:48 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Dongdong Tian --- doc/contributing.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/contributing.md b/doc/contributing.md index b341fa739ad..146809203f1 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -317,9 +317,10 @@ Open `doc/_build/html/index.html` in your browser to view the pages. Follow the ### Adding example code -Many of the PyGMT functions have example code in their documentation. To contribute an example, add an "Example header" -and put the example code below it. Have all lines begin with ">>>". To keep this example code from being run during -testing, add the code "__doctest_skip__ = [function name]" to the top of the module. +Many of the PyGMT functions have example code in their documentation. To contribute an +example, add an "Example" header and put the example code below it. Have all lines +begin with `>>>`. To keep this example code from being run during testing, add the code +`__doctest_skip__ = [function name]` to the top of the module. **Inline code example**