Add basic documentation #26

jambonrose · 2017-08-17T19:01:22Z

This commit:

adds a code of conduct
adds contributing document
adds service badges to the Read Me
adds the basic structure for Sphinx documentation
creates templates for issues and pull-requests

codecov · 2017-08-17T19:20:13Z

Codecov Report

Merging #26 into development will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           development    #26   +/-   ##
==========================================
  Coverage          100%   100%           
==========================================
  Files                7      7           
  Lines              171    171           
  Branches            11     11           
==========================================
  Hits               171    171

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b9294de...20a882a. Read the comment docs.

Jimillback01

OK

Jimillback01

Very minuscule point but maybe the last sentence which ends with the URL should have a period at the end to close the sentence out.

Jimillback01

This may not be a problem, but when I open up the page using "View", the Issue template starts with "Specification" and all the sentences before that are not shown. Further, only the title headings are shown, not any of the sentences defining those headings.
(These do look like HTML comments, so that might be OK).

Jimillback01

Possible issues:

"We will look at the issues and pull-requests as soon as possible." - the dash between pull and requests maybe isn't needed.
"or notes that it is claimed in in the comments..." - maybe should be "..are in the comments,,,"
"on the issue to avoid duplication work" - maybe should be "to avoid duplicate work"
"Use your best judgement to assess the situation" - the spelling should be "judgment".
"your contribution would be welcome." - should end with the past tense "welcomed"
"Read to contribute?" - I think it should start with "Ready..."

Jimillback01

OK

Jimillback01 · 2017-08-17T21:17:48Z

CODE_OF_CONDUCT.md

+[http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/


Very minuscule point but maybe the last sentence which ends with the URL should have a period at the end to close the sentence out.

Jimillback01 · 2017-08-17T21:18:38Z

.github/ISSUE_TEMPLATE.md

+* Fill out what you can
+* Delete what you do not fill out
+-->
+


This may not be a problem, but when I open up the page using "View", the Issue template starts with "Specification" and all the sentences before that are not shown. Further, only the title headings are shown, not any of the sentences defining those headings.
(These do look like HTML comments, so that might be OK).

This is my first time setting up Github templates - my understanding is that the comment will be shown to the developer writing the issue, but that (in the event they don't delete the comment) the comment won't be shown. If my understanding is correct, then the comment is desirable. If not, then we should be changing this. Unfortunately, we won't really know until we merge this. ¯\_(ツ)_/¯

Jimillback01 · 2017-08-17T21:20:56Z

CONTRIBUTING.rst

+request.
+
+Please remember that this is a volunteer-driven project. We will look at
+the issues and pull-requests as soon as possible.


Is the dash proper? Or should it be 2 words here?

2 words. Thanks!

Jimillback01 · 2017-08-17T21:22:13Z

CONTRIBUTING.rst

+
+Look through the `Github issue tracker`_ for bugs. Anything tagged with "bug"
+and "help wanted" is open to whoever wants to implement it. If someone
+has been assigned, or notes that it is claimed in in the comments,


maybe remove the double "in".

Jimillback01 · 2017-08-17T21:22:57Z

CONTRIBUTING.rst

+and "help wanted" is open to whoever wants to implement it. If someone
+has been assigned, or notes that it is claimed in in the comments,
+please reach out to them to work together on the issue to avoid
+duplication work. Note that, as volunteers, people sometime are unable


Maybe make this "duplicate".

Jimillback01 · 2017-08-17T21:23:50Z

CONTRIBUTING.rst

+duplication work. Note that, as volunteers, people sometime are unable
+to complete work they start, and that it is reasonable after a certain
+amount of time to assume they are no longer working on the issue. Use
+your best judgement to assess the situation.


Misspell - should be "judgment".

Jimillback01 · 2017-08-17T21:24:56Z

CONTRIBUTING.rst

+The documentation aims to provide reference material, how-to guides, and
+a general tutorial for getting started with Django and
+django-improved-user. If you believe the documentation can be expanded
+or added to, your contribution would be welcome.


Maybe use the past tense "welcomed" to match above verbs "expanded" and "added".

Jimillback01 · 2017-08-17T21:25:27Z

CONTRIBUTING.rst

+Your First Contribution
+----------------------------
+
+Read to contribute? Let's get django-improved-user working on your local


First word is probably "Ready".

Jimillback01 · 2017-08-17T21:28:07Z

README.rst

+        :alt: Updates
+
+.. end-badges
+
 Read Me


Below, there are 2 links that use the wrong format. This wasn't part of the change, so I can't tie this comment directly to the lines where they occur. Sorry.

No worries! Thank you for pointing this out. I believe that 6b3ab4d fixes this. In the future, feel free to open an issue.

Jimillback01 · 2017-08-17T21:31:57Z

docs/conf.py

+# Django Improved User documentation build configuration file, created by
+# sphinx-quickstart on Thu Aug 17 10:44:16 2017.
+#
+# This file is execfile()d with the current directory set to its


Just a question - is the execfile()d proper?

A great question. I don't really know! Given that it's generated by Sphinx, I'm going to leave it. ¯\_(ツ)_/¯

Jimillback01 · 2017-08-17T21:36:56Z

docs/conf.py

+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path


Should be "These patterns". I'd suggest changing "effect" because it is vague to me. Does it mean the patterns are added to these two specific paths? Or overwrite both paths? Or delete from both paths?

I've changed this to read:

# This list of exclusions will affect the files found in the paths # specified in html_static_path and html_extra_path

I believe that is right, but I am not 100% sure.

Jimillback01 · 2017-08-17T21:38:38Z

docs/conf.py

+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.


Should be "built-in" I think.

Jimillback01 · 2017-08-17T21:39:36Z

docs/conf.py

+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,


Again, I think it should be "built-in"

Jimillback01 · 2017-08-17T21:39:55Z

docs/conf.py

+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".


Again for "built-in".

jambonrose added 12 commits August 14, 2017 19:49

Add badges to ReadMe document

fda2b04

Add badge for Django support

7001609

Fix link in History

fd24cdb

Add list of authors to project

e3c4f4f

Add AppVeyor badge

c3209b7

Add Contributor Covenant

e1e40f0

Write Issue and PR templates for github

c3d1571

First pass at doc about how to contribute

6e54ee7

Fix code refs and typos in History

a6dbb7d

Install Sphinx and RTD theme for Sphinx

d432d89

Create documentation with sphinx-quickstart

49c2b87

Import contributing documentation in Sphinx

f653f62

Jimillback01 approved these changes Aug 17, 2017

View reviewed changes

Jimillback01 suggested changes Aug 17, 2017

View reviewed changes

Jimillback01 approved these changes Aug 17, 2017

View reviewed changes

Jimillback01 reviewed Aug 17, 2017

View reviewed changes

Thank you to Jim Illback

314748d

Jimillback01 reviewed Aug 17, 2017

View reviewed changes

jambonrose added 11 commits August 17, 2017 14:43

Fix formatting in ReadMe

6b3ab4d

Add period to end of sentence in CoC

ec7a7e8

Remove hyphen from pull-request

b75e616

Remove double 'in' in sentence

a6da5cf

Typo: duplication -> duplicating

be6aa51

Typo: judgement -> judgment

5171000

Typo: welcome -> welcomed

911cab9

Typo: Read -> Ready

e7bcf15

Clarify comment in Sphinx conf

59a759a

Typos: builtin -> built-in

2ebaea2

Update Manifest for documentation

20a882a

jambonrose merged commit ec3f6fd into development Aug 17, 2017

jambonrose deleted the initial_documentation branch August 17, 2017 22:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add basic documentation #26

Add basic documentation #26

jambonrose commented Aug 17, 2017

codecov bot commented Aug 17, 2017 •

edited

Loading

Jimillback01 left a comment

Jimillback01 left a comment

Jimillback01 left a comment

Jimillback01 left a comment

Jimillback01 left a comment

Jimillback01 Aug 17, 2017

Jimillback01 Aug 17, 2017

jambonrose Aug 17, 2017 •

edited

Loading

Jimillback01 Aug 17, 2017

jambonrose Aug 17, 2017

Jimillback01 Aug 17, 2017

Jimillback01 Aug 17, 2017

Jimillback01 Aug 17, 2017

Jimillback01 Aug 17, 2017

Jimillback01 Aug 17, 2017

Jimillback01 Aug 17, 2017

jambonrose Aug 17, 2017

Jimillback01 Aug 17, 2017

jambonrose Aug 17, 2017

Jimillback01 Aug 17, 2017 •

edited

Loading

jambonrose Aug 17, 2017

Jimillback01 Aug 17, 2017

Jimillback01 Aug 17, 2017

Jimillback01 Aug 17, 2017

Add basic documentation #26

Add basic documentation #26

Conversation

jambonrose commented Aug 17, 2017

codecov bot commented Aug 17, 2017 • edited Loading

Codecov Report

Jimillback01 left a comment

Choose a reason for hiding this comment

Jimillback01 left a comment

Choose a reason for hiding this comment

Jimillback01 left a comment

Choose a reason for hiding this comment

Jimillback01 left a comment

Choose a reason for hiding this comment

Jimillback01 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jambonrose Aug 17, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Jimillback01 Aug 17, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Aug 17, 2017 •

edited

Loading

jambonrose Aug 17, 2017 •

edited

Loading

Jimillback01 Aug 17, 2017 •

edited

Loading