{"action":"created","comment":{"url":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/comments/242548117","pull_request_review_id":186077249,"id":242548117,"node_id":"MDI0OlB1bGxSZXF1ZXN0UmV2aWV3Q29tbWVudDI0MjU0ODExNw==","diff_hunk":"@@ -0,0 +1,150 @@\n+.. _exttuto-helloworld:\n+\n+Developing a \"Hello world\" directive\n+====================================\n+\n+The objective of this tutorial is to create a very basic extension that adds a new\n+directive that outputs a paragraph containing `hello world`.\n+\n+Only basic information is provided in this tutorial. For more information,\n+refer to the :ref:`other tutorials <extensiontutos>` that go into more\n+details.\n+\n+.. warning:: For this extension, you will need some basic understanding of docutils_\n+   and Python.\n+\n+Creating a new extension file\n+-----------------------------\n+\n+Your extension file could be in any folder of your project. In our case,\n+let's do the following:\n+\n+#. Create an :file:`_ext` folder in :file:`source`.\n+#. Create a new Python file in the :file:`_ext` folder called\n+   :file:`helloworld.py`.\n+\n+   Here is an example of the folder structure you might obtain:\n+\n+   .. code-block:: text\n+\n+         └── source\n+             ├── _ext\n+             │   └── helloworld.py\n+             ├── _static\n+             ├── _themes\n+             ├── conf.py\n+             ├── somefolder\n+             ├── somefile.rst\n+             └── someotherfile.rst\n+\n+Writing the extension\n+---------------------\n+\n+Open :file:`helloworld.py` and paste the following code in it:\n+\n+.. code-block:: python\n+\n+   from docutils import nodes\n+   from docutils.parsers.rst import Directive\n+\n+\n+   class HelloWorld(Directive):\n+       def run(self):\n+           paragraph_node = nodes.paragraph(text='Hello World!')\n+           return [paragraph_node]\n+\n+\n+   def setup(app):\n+       app.add_directive(\"helloworld\", HelloWorld)\n+\n+\n+Some essential things are happening in this example, and you will see them\n+in all directives:\n+\n+.. rubric:: Directive declaration\n+\n+Our new directive is declared in the :code:`HelloWorld` class, it extends\n+docutils_' code:`Directive` class. All extensions that create directives\n+should extend this class.\n+\n+.. rubric:: `run` method\n+\n+This method is a requirement and it is part of every directive. It contains\n+the main logic of the directive and it returns a list of docutils nodes to\n+be processed by Sphinx.\n+\n+Read more on this topic in :ref:`exttuto-todo`.\n+\n+.. rubric:: docutils nodes\n+\n+The `run` method returns a list of nodes. Nodes are docutils' way of\n+representing the content of a document. There are many types of nodes\n+available: text, paragraph, reference, table, etc.\n+\n+Read more about `docutils nodes`_.\n+\n+You can also create your own nodes if needed, refer to the\n+:ref:`exttuto-todo` for more information.","path":"doc/extdev/tutorials/helloworld_ext.rst","position":87,"original_position":87,"commit_id":"adc1d2b59dc6621379ecc9f0c9e6fc10b3c4ab36","original_commit_id":"adc1d2b59dc6621379ecc9f0c9e6fc10b3c4ab36","user":{"login":"stephenfin","id":1690835,"node_id":"MDQ6VXNlcjE2OTA4MzU=","avatar_url":"https://avatars2.githubusercontent.com/u/1690835?v=4","gravatar_id":"","url":"https://api.github.com/users/stephenfin","html_url":"https://github.com/stephenfin","followers_url":"https://api.github.com/users/stephenfin/followers","following_url":"https://api.github.com/users/stephenfin/following{/other_user}","gists_url":"https://api.github.com/users/stephenfin/gists{/gist_id}","starred_url":"https://api.github.com/users/stephenfin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/stephenfin/subscriptions","organizations_url":"https://api.github.com/users/stephenfin/orgs","repos_url":"https://api.github.com/users/stephenfin/repos","events_url":"https://api.github.com/users/stephenfin/events{/privacy}","received_events_url":"https://api.github.com/users/stephenfin/received_events","type":"User","site_admin":false},"body":"This probably makes sense in a section at the end of the document called \"Futher reading\" or similar","created_at":"2018-12-18T14:05:05Z","updated_at":"2018-12-18T14:19:41Z","html_url":"https://github.com/sphinx-doc/sphinx/pull/5678#discussion_r242548117","pull_request_url":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/5678","author_association":"CONTRIBUTOR","_links":{"self":{"href":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/comments/242548117"},"html":{"href":"https://github.com/sphinx-doc/sphinx/pull/5678#discussion_r242548117"},"pull_request":{"href":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/5678"}}},"pull_request":{"url":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/5678","id":234457526,"node_id":"MDExOlB1bGxSZXF1ZXN0MjM0NDU3NTI2","html_url":"https://github.com/sphinx-doc/sphinx/pull/5678","diff_url":"https://github.com/sphinx-doc/sphinx/pull/5678.diff","patch_url":"https://github.com/sphinx-doc/sphinx/pull/5678.patch","issue_url":"https://api.github.com/repos/sphinx-doc/sphinx/issues/5678","number":5678,"state":"open","locked":false,"title":"Docs: Extension tutorial portal + helloworld example","user":{"login":"ArtFlag","id":25686502,"node_id":"MDQ6VXNlcjI1Njg2NTAy","avatar_url":"https://avatars2.githubusercontent.com/u/25686502?v=4","gravatar_id":"","url":"https://api.github.com/users/ArtFlag","html_url":"https://github.com/ArtFlag","followers_url":"https://api.github.com/users/ArtFlag/followers","following_url":"https://api.github.com/users/ArtFlag/following{/other_user}","gists_url":"https://api.github.com/users/ArtFlag/gists{/gist_id}","starred_url":"https://api.github.com/users/ArtFlag/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ArtFlag/subscriptions","organizations_url":"https://api.github.com/users/ArtFlag/orgs","repos_url":"https://api.github.com/users/ArtFlag/repos","events_url":"https://api.github.com/users/ArtFlag/events{/privacy}","received_events_url":"https://api.github.com/users/ArtFlag/received_events","type":"User","site_admin":false},"body":"### Subject\r\n- Promote easy add of extension tutorials by creating a new index page.\r\n- Add a basic hello world tutorial to ease into the Todo list extension tutorial.\r\n\r\n### Relates\r\nRelated to #5585 \r\n\r\n","created_at":"2018-11-28T23:19:38Z","updated_at":"2018-12-18T14:19:41Z","closed_at":null,"merged_at":null,"merge_commit_sha":"4e065d3943a8afce112966009c1a9af8657f2ef5","assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[],"milestone":null,"commits_url":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/5678/commits","review_comments_url":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/5678/comments","review_comment_url":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/comments{/number}","comments_url":"https://api.github.com/repos/sphinx-doc/sphinx/issues/5678/comments","statuses_url":"https://api.github.com/repos/sphinx-doc/sphinx/statuses/adc1d2b59dc6621379ecc9f0c9e6fc10b3c4ab36","head":{"label":"ArtFlag:docs/extension-tutorials","ref":"docs/extension-tutorials","sha":"adc1d2b59dc6621379ecc9f0c9e6fc10b3c4ab36","user":{"login":"ArtFlag","id":25686502,"node_id":"MDQ6VXNlcjI1Njg2NTAy","avatar_url":"https://avatars2.githubusercontent.com/u/25686502?v=4","gravatar_id":"","url":"https://api.github.com/users/ArtFlag","html_url":"https://github.com/ArtFlag","followers_url":"https://api.github.com/users/ArtFlag/followers","following_url":"https://api.github.com/users/ArtFlag/following{/other_user}","gists_url":"https://api.github.com/users/ArtFlag/gists{/gist_id}","starred_url":"https://api.github.com/users/ArtFlag/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ArtFlag/subscriptions","organizations_url":"https://api.github.com/users/ArtFlag/orgs","repos_url":"https://api.github.com/users/ArtFlag/repos","events_url":"https://api.github.com/users/ArtFlag/events{/privacy}","received_events_url":"https://api.github.com/users/ArtFlag/received_events","type":"User","site_admin":false},"repo":{"id":97260952,"node_id":"MDEwOlJlcG9zaXRvcnk5NzI2MDk1Mg==","name":"sphinx","full_name":"ArtFlag/sphinx","private":false,"owner":{"login":"ArtFlag","id":25686502,"node_id":"MDQ6VXNlcjI1Njg2NTAy","avatar_url":"https://avatars2.githubusercontent.com/u/25686502?v=4","gravatar_id":"","url":"https://api.github.com/users/ArtFlag","html_url":"https://github.com/ArtFlag","followers_url":"https://api.github.com/users/ArtFlag/followers","following_url":"https://api.github.com/users/ArtFlag/following{/other_user}","gists_url":"https://api.github.com/users/ArtFlag/gists{/gist_id}","starred_url":"https://api.github.com/users/ArtFlag/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ArtFlag/subscriptions","organizations_url":"https://api.github.com/users/ArtFlag/orgs","repos_url":"https://api.github.com/users/ArtFlag/repos","events_url":"https://api.github.com/users/ArtFlag/events{/privacy}","received_events_url":"https://api.github.com/users/ArtFlag/received_events","type":"User","site_admin":false},"html_url":"https://github.com/ArtFlag/sphinx","description":"Main repository for the Sphinx documentation builder","fork":true,"url":"https://api.github.com/repos/ArtFlag/sphinx","forks_url":"https://api.github.com/repos/ArtFlag/sphinx/forks","keys_url":"https://api.github.com/repos/ArtFlag/sphinx/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ArtFlag/sphinx/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ArtFlag/sphinx/teams","hooks_url":"https://api.github.com/repos/ArtFlag/sphinx/hooks","issue_events_url":"https://api.github.com/repos/ArtFlag/sphinx/issues/events{/number}","events_url":"https://api.github.com/repos/ArtFlag/sphinx/events","assignees_url":"https://api.github.com/repos/ArtFlag/sphinx/assignees{/user}","branches_url":"https://api.github.com/repos/ArtFlag/sphinx/branches{/branch}","tags_url":"https://api.github.com/repos/ArtFlag/sphinx/tags","blobs_url":"https://api.github.com/repos/ArtFlag/sphinx/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ArtFlag/sphinx/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ArtFlag/sphinx/git/refs{/sha}","trees_url":"https://api.github.com/repos/ArtFlag/sphinx/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ArtFlag/sphinx/statuses/{sha}","languages_url":"https://api.github.com/repos/ArtFlag/sphinx/languages","stargazers_url":"https://api.github.com/repos/ArtFlag/sphinx/stargazers","contributors_url":"https://api.github.com/repos/ArtFlag/sphinx/contributors","subscribers_url":"https://api.github.com/repos/ArtFlag/sphinx/subscribers","subscription_url":"https://api.github.com/repos/ArtFlag/sphinx/subscription","commits_url":"https://api.github.com/repos/ArtFlag/sphinx/commits{/sha}","git_commits_url":"https://api.github.com/repos/ArtFlag/sphinx/git/commits{/sha}","comments_url":"https://api.github.com/repos/ArtFlag/sphinx/comments{/number}","issue_comment_url":"https://api.github.com/repos/ArtFlag/sphinx/issues/comments{/number}","contents_url":"https://api.github.com/repos/ArtFlag/sphinx/contents/{+path}","compare_url":"https://api.github.com/repos/ArtFlag/sphinx/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ArtFlag/sphinx/merges","archive_url":"https://api.github.com/repos/ArtFlag/sphinx/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ArtFlag/sphinx/downloads","issues_url":"https://api.github.com/repos/ArtFlag/sphinx/issues{/number}","pulls_url":"https://api.github.com/repos/ArtFlag/sphinx/pulls{/number}","milestones_url":"https://api.github.com/repos/ArtFlag/sphinx/milestones{/number}","notifications_url":"https://api.github.com/repos/ArtFlag/sphinx/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ArtFlag/sphinx/labels{/name}","releases_url":"https://api.github.com/repos/ArtFlag/sphinx/releases{/id}","deployments_url":"https://api.github.com/repos/ArtFlag/sphinx/deployments","created_at":"2017-07-14T18:11:24Z","updated_at":"2017-07-14T18:11:28Z","pushed_at":"2018-11-30T09:33:21Z","git_url":"git://github.com/ArtFlag/sphinx.git","ssh_url":"git@github.com:ArtFlag/sphinx.git","clone_url":"https://github.com/ArtFlag/sphinx.git","svn_url":"https://github.com/ArtFlag/sphinx","homepage":"http://sphinx-doc.org","size":31400,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":0,"license":{"key":"other","name":"Other","spdx_id":"NOASSERTION","url":null,"node_id":"MDc6TGljZW5zZTA="},"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"sphinx-doc:master","ref":"master","sha":"3528a68d2a2869425fd71b3a12856b8599c83d15","user":{"login":"sphinx-doc","id":9928167,"node_id":"MDEyOk9yZ2FuaXphdGlvbjk5MjgxNjc=","avatar_url":"https://avatars2.githubusercontent.com/u/9928167?v=4","gravatar_id":"","url":"https://api.github.com/users/sphinx-doc","html_url":"https://github.com/sphinx-doc","followers_url":"https://api.github.com/users/sphinx-doc/followers","following_url":"https://api.github.com/users/sphinx-doc/following{/other_user}","gists_url":"https://api.github.com/users/sphinx-doc/gists{/gist_id}","starred_url":"https://api.github.com/users/sphinx-doc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sphinx-doc/subscriptions","organizations_url":"https://api.github.com/users/sphinx-doc/orgs","repos_url":"https://api.github.com/users/sphinx-doc/repos","events_url":"https://api.github.com/users/sphinx-doc/events{/privacy}","received_events_url":"https://api.github.com/users/sphinx-doc/received_events","type":"Organization","site_admin":false},"repo":{"id":28710753,"node_id":"MDEwOlJlcG9zaXRvcnkyODcxMDc1Mw==","name":"sphinx","full_name":"sphinx-doc/sphinx","private":false,"owner":{"login":"sphinx-doc","id":9928167,"node_id":"MDEyOk9yZ2FuaXphdGlvbjk5MjgxNjc=","avatar_url":"https://avatars2.githubusercontent.com/u/9928167?v=4","gravatar_id":"","url":"https://api.github.com/users/sphinx-doc","html_url":"https://github.com/sphinx-doc","followers_url":"https://api.github.com/users/sphinx-doc/followers","following_url":"https://api.github.com/users/sphinx-doc/following{/other_user}","gists_url":"https://api.github.com/users/sphinx-doc/gists{/gist_id}","starred_url":"https://api.github.com/users/sphinx-doc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sphinx-doc/subscriptions","organizations_url":"https://api.github.com/users/sphinx-doc/orgs","repos_url":"https://api.github.com/users/sphinx-doc/repos","events_url":"https://api.github.com/users/sphinx-doc/events{/privacy}","received_events_url":"https://api.github.com/users/sphinx-doc/received_events","type":"Organization","site_admin":false},"html_url":"https://github.com/sphinx-doc/sphinx","description":"Main repository for the Sphinx documentation builder","fork":false,"url":"https://api.github.com/repos/sphinx-doc/sphinx","forks_url":"https://api.github.com/repos/sphinx-doc/sphinx/forks","keys_url":"https://api.github.com/repos/sphinx-doc/sphinx/keys{/key_id}","collaborators_url":"https://api.github.com/repos/sphinx-doc/sphinx/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/sphinx-doc/sphinx/teams","hooks_url":"https://api.github.com/repos/sphinx-doc/sphinx/hooks","issue_events_url":"https://api.github.com/repos/sphinx-doc/sphinx/issues/events{/number}","events_url":"https://api.github.com/repos/sphinx-doc/sphinx/events","assignees_url":"https://api.github.com/repos/sphinx-doc/sphinx/assignees{/user}","branches_url":"https://api.github.com/repos/sphinx-doc/sphinx/branches{/branch}","tags_url":"https://api.github.com/repos/sphinx-doc/sphinx/tags","blobs_url":"https://api.github.com/repos/sphinx-doc/sphinx/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/sphinx-doc/sphinx/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/sphinx-doc/sphinx/git/refs{/sha}","trees_url":"https://api.github.com/repos/sphinx-doc/sphinx/git/trees{/sha}","statuses_url":"https://api.github.com/repos/sphinx-doc/sphinx/statuses/{sha}","languages_url":"https://api.github.com/repos/sphinx-doc/sphinx/languages","stargazers_url":"https://api.github.com/repos/sphinx-doc/sphinx/stargazers","contributors_url":"https://api.github.com/repos/sphinx-doc/sphinx/contributors","subscribers_url":"https://api.github.com/repos/sphinx-doc/sphinx/subscribers","subscription_url":"https://api.github.com/repos/sphinx-doc/sphinx/subscription","commits_url":"https://api.github.com/repos/sphinx-doc/sphinx/commits{/sha}","git_commits_url":"https://api.github.com/repos/sphinx-doc/sphinx/git/commits{/sha}","comments_url":"https://api.github.com/repos/sphinx-doc/sphinx/comments{/number}","issue_comment_url":"https://api.github.com/repos/sphinx-doc/sphinx/issues/comments{/number}","contents_url":"https://api.github.com/repos/sphinx-doc/sphinx/contents/{+path}","compare_url":"https://api.github.com/repos/sphinx-doc/sphinx/compare/{base}...{head}","merges_url":"https://api.github.com/repos/sphinx-doc/sphinx/merges","archive_url":"https://api.github.com/repos/sphinx-doc/sphinx/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/sphinx-doc/sphinx/downloads","issues_url":"https://api.github.com/repos/sphinx-doc/sphinx/issues{/number}","pulls_url":"https://api.github.com/repos/sphinx-doc/sphinx/pulls{/number}","milestones_url":"https://api.github.com/repos/sphinx-doc/sphinx/milestones{/number}","notifications_url":"https://api.github.com/repos/sphinx-doc/sphinx/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/sphinx-doc/sphinx/labels{/name}","releases_url":"https://api.github.com/repos/sphinx-doc/sphinx/releases{/id}","deployments_url":"https://api.github.com/repos/sphinx-doc/sphinx/deployments","created_at":"2015-01-02T10:53:28Z","updated_at":"2018-12-18T14:17:30Z","pushed_at":"2018-12-18T14:17:20Z","git_url":"git://github.com/sphinx-doc/sphinx.git","ssh_url":"git@github.com:sphinx-doc/sphinx.git","clone_url":"https://github.com/sphinx-doc/sphinx.git","svn_url":"https://github.com/sphinx-doc/sphinx","homepage":"http://sphinx-doc.org","size":34742,"stargazers_count":2294,"watchers_count":2294,"language":"Python","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":935,"mirror_url":null,"archived":false,"open_issues_count":698,"license":{"key":"other","name":"Other","spdx_id":"NOASSERTION","url":null,"node_id":"MDc6TGljZW5zZTA="},"forks":935,"open_issues":698,"watchers":2294,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/5678"},"html":{"href":"https://github.com/sphinx-doc/sphinx/pull/5678"},"issue":{"href":"https://api.github.com/repos/sphinx-doc/sphinx/issues/5678"},"comments":{"href":"https://api.github.com/repos/sphinx-doc/sphinx/issues/5678/comments"},"review_comments":{"href":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/5678/comments"},"review_comment":{"href":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/sphinx-doc/sphinx/pulls/5678/commits"},"statuses":{"href":"https://api.github.com/repos/sphinx-doc/sphinx/statuses/adc1d2b59dc6621379ecc9f0c9e6fc10b3c4ab36"}},"author_association":"NONE"}}
{"actor":{"display_login":"stephenfin"}}