{"action":"opened","number":1333,"pull_request":{"url":"https://api.github.com/repos/fonttools/fonttools/pulls/1333","id":222208898,"node_id":"MDExOlB1bGxSZXF1ZXN0MjIyMjA4ODk4","html_url":"https://github.com/fonttools/fonttools/pull/1333","diff_url":"https://github.com/fonttools/fonttools/pull/1333.diff","patch_url":"https://github.com/fonttools/fonttools/pull/1333.patch","issue_url":"https://api.github.com/repos/fonttools/fonttools/issues/1333","number":1333,"state":"open","locked":false,"title":"Sphinx documentation expansion for continuous documentation on Read the Docs","user":{"login":"chrissimpkins","id":4249591,"node_id":"MDQ6VXNlcjQyNDk1OTE=","avatar_url":"https://avatars0.githubusercontent.com/u/4249591?v=4","gravatar_id":"","url":"https://api.github.com/users/chrissimpkins","html_url":"https://github.com/chrissimpkins","followers_url":"https://api.github.com/users/chrissimpkins/followers","following_url":"https://api.github.com/users/chrissimpkins/following{/other_user}","gists_url":"https://api.github.com/users/chrissimpkins/gists{/gist_id}","starred_url":"https://api.github.com/users/chrissimpkins/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chrissimpkins/subscriptions","organizations_url":"https://api.github.com/users/chrissimpkins/orgs","repos_url":"https://api.github.com/users/chrissimpkins/repos","events_url":"https://api.github.com/users/chrissimpkins/events{/privacy}","received_events_url":"https://api.github.com/users/chrissimpkins/received_events","type":"User","site_admin":false},"body":"This PR expands on the efforts by @gferreira @anthrotype @belluzj @LettError @mashabow to create Sphinx formatted `*.rst` documentation for the fontTools project.  With this PR, all fontTools modules (including all submodules) are now included in the Sphinx documentation available in the `Doc` directory and we *should*™ be ready to push to RTD for continuous documentation of the fontTools project.\r\n\r\nThe PR adds the following:\r\n\r\n- new `*.rst` files for modules that were not previously documented with support for automation of source docstring parsing --> formatted documentation with paths organized to match the module paths in the source\r\n- translation of the fontTools README to `*.rst` format for use as the home page (index.html) of the Sphinx documentation (with minor formatting updates)\r\n- Sphinx extension support for local builds of documentation that match the RTD theme (see `Doc/README.md` for install/use details\r\n- Sphinx [Napoleon extension](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/) support for automated parsing of Google Style Guide formatted Python docstrings to documentation files.  This is a much more human legible format than the default Sphinx docstring approach.\r\n- new documentation README in the root of the `Doc` directory with comment style guidelines, local build instructions, and contributor guidelines\r\n- new CC by-SA 4.0 International License for documentation (defined in `Doc/source/conf.py` file)\r\n\r\nI took some liberties with formatting on the `*.rst` doc side but did not modify existing documentation in Python source files or make significant changes to the documentation text used for the translations of existing README text files to this format.  There were no changes to existing documentation in the project README or any other existing documentation files.  These changes support the start of the source documentation work and a great deal of new and modified docstring text will be necessary if we want to use this approach for comprehensive, continuous source documentation.  \r\n\r\nFor those who would like to build a local set of docs to view these changes, use the following instructions:\r\n\r\n(1) setup a development environment for the fontTools repository as per instructions on the repository README\r\n(2) install the Python documentation build dependencies:\r\n\r\n```\r\npip3 install sphinx sphinxcontrib-napoleon sphinx-rtd-theme\r\n```\r\n\r\n(3) navigate to the `Doc` directory of the fontTools repository and compile the documentation with one of the two following approaches (based upon availability of `make` on your system):\r\n\r\n```\r\nmake html\r\n```\r\n\r\nor\r\n\r\n```\r\nsphinx-build -b html source build\r\n```\r\n\r\nThe documentation is built on the path `Doc/build/html`.  Open the `index.html` file on that path in your browser to view the home page.\r\n\r\nHere are a couple of previews of local builds that use the RTD theme to see where we are:\r\n\r\n### Docs Home\r\n![1mfls-image-crunch](https://user-images.githubusercontent.com/4249591/46819650-4ac16200-cd52-11e8-8776-7e67785258e9.png)\r\n\r\n### ttLib.ttFont module\r\n![1awdd-image-crunch](https://user-images.githubusercontent.com/4249591/46819675-590f7e00-cd52-11e8-98bb-a6b059f19e06.png)\r\n\r\n\r\n### TODO:\r\n\r\n- [ ] Is Google Style Guide docstring formatting the best approach going forward? (if not, modify the `Doc/README.md`\r\n- [ ] Is CC BY-SA 4.0 an acceptable license for documentation? (if not, modify the `Doc/source/conf.py` field that defines this)\r\n- [ ] Push to RTD to confirm that this builds and displays properly.  It is possible to build from a working non-master branch on the RTD side.  Must be performed by someone with edit privileges on the repository.  As I understand the RTD documentation, the entire repo is walked to identify the `conf.py` file and the build is performed in that directory.  If it does not work, it *should* be a simple refactor of directory/file paths to support the remote builds.\r\n- [ ] add RTD URL to the `Doc/README.md` file when available\r\n\r\n### Active Issues That Have Not Been Addressed\r\n\r\n- `misc.symfont` module documentation does not auto populate with module members using autodoc because the `sympy` dependency is not installed by default\r\n- `pens.reportLabPen` module documentation does not auto populate with module members using autodoc because `reportLab` dependency is not installed by default\r\n- there are a lengthy series of docstring warnings that are displayed when you `make html` build the documentation.  These will need to be reviewed and may need to be addressed as part of future work.\r\n\r\nAssociated issue reports:\r\n\r\n- https://github.com/fonttools/fonttools/issues/1266\r\n- https://github.com/fonttools/fonttools/issues/997\r\n- https://github.com/fonttools/fonttools/issues/984\r\n\r\nCloses #984 ","created_at":"2018-10-11T16:52:53Z","updated_at":"2018-10-11T16:52:53Z","closed_at":null,"merged_at":null,"merge_commit_sha":null,"assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[],"milestone":null,"commits_url":"https://api.github.com/repos/fonttools/fonttools/pulls/1333/commits","review_comments_url":"https://api.github.com/repos/fonttools/fonttools/pulls/1333/comments","review_comment_url":"https://api.github.com/repos/fonttools/fonttools/pulls/comments{/number}","comments_url":"https://api.github.com/repos/fonttools/fonttools/issues/1333/comments","statuses_url":"https://api.github.com/repos/fonttools/fonttools/statuses/d08d2d9db6f351a6dbd22f087193ec3c4ed90d80","head":{"label":"chrissimpkins:readthedocs","ref":"readthedocs","sha":"d08d2d9db6f351a6dbd22f087193ec3c4ed90d80","user":{"login":"chrissimpkins","id":4249591,"node_id":"MDQ6VXNlcjQyNDk1OTE=","avatar_url":"https://avatars0.githubusercontent.com/u/4249591?v=4","gravatar_id":"","url":"https://api.github.com/users/chrissimpkins","html_url":"https://github.com/chrissimpkins","followers_url":"https://api.github.com/users/chrissimpkins/followers","following_url":"https://api.github.com/users/chrissimpkins/following{/other_user}","gists_url":"https://api.github.com/users/chrissimpkins/gists{/gist_id}","starred_url":"https://api.github.com/users/chrissimpkins/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chrissimpkins/subscriptions","organizations_url":"https://api.github.com/users/chrissimpkins/orgs","repos_url":"https://api.github.com/users/chrissimpkins/repos","events_url":"https://api.github.com/users/chrissimpkins/events{/privacy}","received_events_url":"https://api.github.com/users/chrissimpkins/received_events","type":"User","site_admin":false},"repo":{"id":133195439,"node_id":"MDEwOlJlcG9zaXRvcnkxMzMxOTU0Mzk=","name":"fonttools","full_name":"chrissimpkins/fonttools","private":false,"owner":{"login":"chrissimpkins","id":4249591,"node_id":"MDQ6VXNlcjQyNDk1OTE=","avatar_url":"https://avatars0.githubusercontent.com/u/4249591?v=4","gravatar_id":"","url":"https://api.github.com/users/chrissimpkins","html_url":"https://github.com/chrissimpkins","followers_url":"https://api.github.com/users/chrissimpkins/followers","following_url":"https://api.github.com/users/chrissimpkins/following{/other_user}","gists_url":"https://api.github.com/users/chrissimpkins/gists{/gist_id}","starred_url":"https://api.github.com/users/chrissimpkins/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chrissimpkins/subscriptions","organizations_url":"https://api.github.com/users/chrissimpkins/orgs","repos_url":"https://api.github.com/users/chrissimpkins/repos","events_url":"https://api.github.com/users/chrissimpkins/events{/privacy}","received_events_url":"https://api.github.com/users/chrissimpkins/received_events","type":"User","site_admin":false},"html_url":"https://github.com/chrissimpkins/fonttools","description":"A library to manipulate font files from Python.","fork":true,"url":"https://api.github.com/repos/chrissimpkins/fonttools","forks_url":"https://api.github.com/repos/chrissimpkins/fonttools/forks","keys_url":"https://api.github.com/repos/chrissimpkins/fonttools/keys{/key_id}","collaborators_url":"https://api.github.com/repos/chrissimpkins/fonttools/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/chrissimpkins/fonttools/teams","hooks_url":"https://api.github.com/repos/chrissimpkins/fonttools/hooks","issue_events_url":"https://api.github.com/repos/chrissimpkins/fonttools/issues/events{/number}","events_url":"https://api.github.com/repos/chrissimpkins/fonttools/events","assignees_url":"https://api.github.com/repos/chrissimpkins/fonttools/assignees{/user}","branches_url":"https://api.github.com/repos/chrissimpkins/fonttools/branches{/branch}","tags_url":"https://api.github.com/repos/chrissimpkins/fonttools/tags","blobs_url":"https://api.github.com/repos/chrissimpkins/fonttools/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/chrissimpkins/fonttools/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/chrissimpkins/fonttools/git/refs{/sha}","trees_url":"https://api.github.com/repos/chrissimpkins/fonttools/git/trees{/sha}","statuses_url":"https://api.github.com/repos/chrissimpkins/fonttools/statuses/{sha}","languages_url":"https://api.github.com/repos/chrissimpkins/fonttools/languages","stargazers_url":"https://api.github.com/repos/chrissimpkins/fonttools/stargazers","contributors_url":"https://api.github.com/repos/chrissimpkins/fonttools/contributors","subscribers_url":"https://api.github.com/repos/chrissimpkins/fonttools/subscribers","subscription_url":"https://api.github.com/repos/chrissimpkins/fonttools/subscription","commits_url":"https://api.github.com/repos/chrissimpkins/fonttools/commits{/sha}","git_commits_url":"https://api.github.com/repos/chrissimpkins/fonttools/git/commits{/sha}","comments_url":"https://api.github.com/repos/chrissimpkins/fonttools/comments{/number}","issue_comment_url":"https://api.github.com/repos/chrissimpkins/fonttools/issues/comments{/number}","contents_url":"https://api.github.com/repos/chrissimpkins/fonttools/contents/{+path}","compare_url":"https://api.github.com/repos/chrissimpkins/fonttools/compare/{base}...{head}","merges_url":"https://api.github.com/repos/chrissimpkins/fonttools/merges","archive_url":"https://api.github.com/repos/chrissimpkins/fonttools/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/chrissimpkins/fonttools/downloads","issues_url":"https://api.github.com/repos/chrissimpkins/fonttools/issues{/number}","pulls_url":"https://api.github.com/repos/chrissimpkins/fonttools/pulls{/number}","milestones_url":"https://api.github.com/repos/chrissimpkins/fonttools/milestones{/number}","notifications_url":"https://api.github.com/repos/chrissimpkins/fonttools/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/chrissimpkins/fonttools/labels{/name}","releases_url":"https://api.github.com/repos/chrissimpkins/fonttools/releases{/id}","deployments_url":"https://api.github.com/repos/chrissimpkins/fonttools/deployments","created_at":"2018-05-13T01:09:21Z","updated_at":"2018-10-10T17:20:04Z","pushed_at":"2018-10-11T15:50:26Z","git_url":"git://github.com/chrissimpkins/fonttools.git","ssh_url":"git@github.com:chrissimpkins/fonttools.git","clone_url":"https://github.com/chrissimpkins/fonttools.git","svn_url":"https://github.com/chrissimpkins/fonttools","homepage":"https://groups.google.com/d/forum/fonttools","size":8801,"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":"fonttools:master","ref":"master","sha":"befcb4d57e51102d8257e080d95f13d900b319b6","user":{"login":"fonttools","id":20555868,"node_id":"MDEyOk9yZ2FuaXphdGlvbjIwNTU1ODY4","avatar_url":"https://avatars3.githubusercontent.com/u/20555868?v=4","gravatar_id":"","url":"https://api.github.com/users/fonttools","html_url":"https://github.com/fonttools","followers_url":"https://api.github.com/users/fonttools/followers","following_url":"https://api.github.com/users/fonttools/following{/other_user}","gists_url":"https://api.github.com/users/fonttools/gists{/gist_id}","starred_url":"https://api.github.com/users/fonttools/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fonttools/subscriptions","organizations_url":"https://api.github.com/users/fonttools/orgs","repos_url":"https://api.github.com/users/fonttools/repos","events_url":"https://api.github.com/users/fonttools/events{/privacy}","received_events_url":"https://api.github.com/users/fonttools/received_events","type":"Organization","site_admin":false},"repo":{"id":11639637,"node_id":"MDEwOlJlcG9zaXRvcnkxMTYzOTYzNw==","name":"fonttools","full_name":"fonttools/fonttools","private":false,"owner":{"login":"fonttools","id":20555868,"node_id":"MDEyOk9yZ2FuaXphdGlvbjIwNTU1ODY4","avatar_url":"https://avatars3.githubusercontent.com/u/20555868?v=4","gravatar_id":"","url":"https://api.github.com/users/fonttools","html_url":"https://github.com/fonttools","followers_url":"https://api.github.com/users/fonttools/followers","following_url":"https://api.github.com/users/fonttools/following{/other_user}","gists_url":"https://api.github.com/users/fonttools/gists{/gist_id}","starred_url":"https://api.github.com/users/fonttools/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fonttools/subscriptions","organizations_url":"https://api.github.com/users/fonttools/orgs","repos_url":"https://api.github.com/users/fonttools/repos","events_url":"https://api.github.com/users/fonttools/events{/privacy}","received_events_url":"https://api.github.com/users/fonttools/received_events","type":"Organization","site_admin":false},"html_url":"https://github.com/fonttools/fonttools","description":"A library to manipulate font files from Python.","fork":false,"url":"https://api.github.com/repos/fonttools/fonttools","forks_url":"https://api.github.com/repos/fonttools/fonttools/forks","keys_url":"https://api.github.com/repos/fonttools/fonttools/keys{/key_id}","collaborators_url":"https://api.github.com/repos/fonttools/fonttools/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/fonttools/fonttools/teams","hooks_url":"https://api.github.com/repos/fonttools/fonttools/hooks","issue_events_url":"https://api.github.com/repos/fonttools/fonttools/issues/events{/number}","events_url":"https://api.github.com/repos/fonttools/fonttools/events","assignees_url":"https://api.github.com/repos/fonttools/fonttools/assignees{/user}","branches_url":"https://api.github.com/repos/fonttools/fonttools/branches{/branch}","tags_url":"https://api.github.com/repos/fonttools/fonttools/tags","blobs_url":"https://api.github.com/repos/fonttools/fonttools/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/fonttools/fonttools/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/fonttools/fonttools/git/refs{/sha}","trees_url":"https://api.github.com/repos/fonttools/fonttools/git/trees{/sha}","statuses_url":"https://api.github.com/repos/fonttools/fonttools/statuses/{sha}","languages_url":"https://api.github.com/repos/fonttools/fonttools/languages","stargazers_url":"https://api.github.com/repos/fonttools/fonttools/stargazers","contributors_url":"https://api.github.com/repos/fonttools/fonttools/contributors","subscribers_url":"https://api.github.com/repos/fonttools/fonttools/subscribers","subscription_url":"https://api.github.com/repos/fonttools/fonttools/subscription","commits_url":"https://api.github.com/repos/fonttools/fonttools/commits{/sha}","git_commits_url":"https://api.github.com/repos/fonttools/fonttools/git/commits{/sha}","comments_url":"https://api.github.com/repos/fonttools/fonttools/comments{/number}","issue_comment_url":"https://api.github.com/repos/fonttools/fonttools/issues/comments{/number}","contents_url":"https://api.github.com/repos/fonttools/fonttools/contents/{+path}","compare_url":"https://api.github.com/repos/fonttools/fonttools/compare/{base}...{head}","merges_url":"https://api.github.com/repos/fonttools/fonttools/merges","archive_url":"https://api.github.com/repos/fonttools/fonttools/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/fonttools/fonttools/downloads","issues_url":"https://api.github.com/repos/fonttools/fonttools/issues{/number}","pulls_url":"https://api.github.com/repos/fonttools/fonttools/pulls{/number}","milestones_url":"https://api.github.com/repos/fonttools/fonttools/milestones{/number}","notifications_url":"https://api.github.com/repos/fonttools/fonttools/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/fonttools/fonttools/labels{/name}","releases_url":"https://api.github.com/repos/fonttools/fonttools/releases{/id}","deployments_url":"https://api.github.com/repos/fonttools/fonttools/deployments","created_at":"2013-07-24T16:28:35Z","updated_at":"2018-10-11T06:59:00Z","pushed_at":"2018-10-11T08:57:37Z","git_url":"git://github.com/fonttools/fonttools.git","ssh_url":"git@github.com:fonttools/fonttools.git","clone_url":"https://github.com/fonttools/fonttools.git","svn_url":"https://github.com/fonttools/fonttools","homepage":"https://groups.google.com/d/forum/fonttools","size":8936,"stargazers_count":1368,"watchers_count":1368,"language":"Python","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":202,"mirror_url":null,"archived":false,"open_issues_count":251,"license":{"key":"other","name":"Other","spdx_id":"NOASSERTION","url":null,"node_id":"MDc6TGljZW5zZTA="},"forks":202,"open_issues":251,"watchers":1368,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/fonttools/fonttools/pulls/1333"},"html":{"href":"https://github.com/fonttools/fonttools/pull/1333"},"issue":{"href":"https://api.github.com/repos/fonttools/fonttools/issues/1333"},"comments":{"href":"https://api.github.com/repos/fonttools/fonttools/issues/1333/comments"},"review_comments":{"href":"https://api.github.com/repos/fonttools/fonttools/pulls/1333/comments"},"review_comment":{"href":"https://api.github.com/repos/fonttools/fonttools/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/fonttools/fonttools/pulls/1333/commits"},"statuses":{"href":"https://api.github.com/repos/fonttools/fonttools/statuses/d08d2d9db6f351a6dbd22f087193ec3c4ed90d80"}},"author_association":"CONTRIBUTOR","merged":false,"mergeable":null,"rebaseable":null,"mergeable_state":"unknown","merged_by":null,"comments":0,"review_comments":0,"maintainer_can_modify":true,"commits":67,"additions":902,"deletions":96,"changed_files":58}}
{"actor":{"display_login":"chrissimpkins"}}