Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Fixed #22141 -- Added spell checker for documentation. #2354

Closed
wants to merge 4 commits into from

3 participants

@beregond

No description provided.

docs/conf.py
@@ -31,7 +31,7 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["djangodocs", "sphinx.ext.intersphinx"]
+extensions = ["djangodocs", "sphinx.ext.intersphinx", "sphinxcontrib.spelling"]
@bmispelon Collaborator

This package is not installed by default which means that with this addition, one can't run make html without installing this.
I don't think it should be a hard requirement. Is it possible to have this extension be required only when running the spelling command?

I'll try to find walkaround.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@bmispelon
Collaborator

I'm not too clear on the purpose of the wordlist file.

Is it a list of words that we use that shouldn't be marked as spelling mistakes? If so, I don't think words like additon should be in there, and I'm also not to keen on having to put proper nouns in there. Can we change that?

@beregond

@bmispelon - wordlist is list of words that are not "proper words" (what in fact evaluates to the fact, that this word is absent in word list, even if it is proper). Some words like 'memcache' or even 'Django' are absent in dictionaries used by pyenchant, so they need to be added to this list, even if these are proper nouns.

Words like additon are ofc my mistake, gonna fix it ;)

@beregond beregond referenced this pull request
Closed

Fixed docs typos. #2353

@bmispelon
Collaborator

The changes to conf.py are good: I can now run make html without having the spelling extension installed. There's probably some improvement to be made on the error message when the extension is not installed but the basic functionality is there.

There's a problem with the return code of the command which makes it believe that it failed:

build finished with problems, 1 warning.
Makefile:150: recipe for target 'spelling' failed
make: *** [spelling] Error 1

Finally, I think there's still some false positives in the word list (and I'm still not keen on the idea of curating such a list) and for some reason, having one raises warnings when building the documentation:

checking consistency... ./django/docs/spelling_wordlist.txt:: WARNING: document isn't included in any toctree
done
@bmispelon
Collaborator

Also, this new feature is probably significant enough that it warrants a ticket, and maybe even a post to the django-developers mailing list.

@beregond

@bmispelon yes, build fails, because it find wrong words. If you i.e. merge also this PR #2353 then build won't find any wrong words and will return success.

"There's probably some improvement to be made on the error message when the extension is not installed but the basic functionality is there." - what do you mean?

Warning - well, yes there is, just as here:

./django/docs/ref/schema-editor.txt:: WARNING: document isn't included in any toctree

only way is to include this list into docs, but I'm not sure if it is a good idea.

"Finally, I think there's still some false positives in the word list" - well, probably you are right ;) I went through this list few times, but anyway there may occur errors.

"and I'm still not keen on the idea of curating such a list" - you mean creating? Well, it is hard to find walkaround, because there always be words, that in fact exist only in Django or programming world, so in the end we would end up with similar list imho.

"Also, this new feature is probably significant enough that it warrants a ticket, and maybe even a post to the django-developers mailing list." - ok

docs/spelling_wordlist.txt
@@ -0,0 +1,783 @@
+Aalto
+accessor
+accesss
+Aceh
+actionnable
@timgraham Owner

actionable*

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/spelling_wordlist.txt
@@ -0,0 +1,783 @@
+Aalto
+accessor
+accesss
@timgraham Owner

access*

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/spelling_wordlist.txt
@@ -0,0 +1,783 @@
+Aalto
+accessor
+accesss
+Aceh
+actionnable
+adaptor
@timgraham Owner

adapter*

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/spelling_wordlist.txt
@@ -0,0 +1,783 @@
+Aalto
+accessor
+accesss
+Aceh
+actionnable
+adaptor
+addslashes
+admin
+admindocs
+admins
+aggregator
+Ai
+Alchin
+amet
+analagous
@timgraham Owner

analogous*

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/spelling_wordlist.txt
((7 lines not shown))
+addslashes
+admin
+admindocs
+admins
+aggregator
+Ai
+Alchin
+amet
+analagous
+Anssi
+api
+apnumber
+Apolloner
+app
+appname
+appplication
@timgraham Owner

application*

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@timgraham
Owner

I've done some additional spelling fixing and edited the word list appropriately, here's a diff to incorporate: http://dpaste.com/1672120/

We should add a brief note about this option to internals/contributing/writing-documentation.txt (link to how to install the checker, how to build the docs with the option, and possibly how to update word list if you have an easy way to do that (e.g. a way to add all the words than exist in the "error" output to the list, if they are indeed actually words)). Would you like to draft something?

Is there a way to put the wordlist at an alternate location so we can avoid this error?
/home/tim/code/django/docs/spelling_wordlist.txt:: WARNING: document isn't included in any toctree

Thanks, I'm looking forward to having this!

@beregond

Ok, I'll update word list.

Yeah, sure, I'll write about this in docs.

I'm sure there is option to change name of file from spelling_wordlist.txt, don't know yet if you can change the location, but I'll try to find some solution.

@bmispelon
Collaborator

In case you haven't found it yet, the option to change the name of the wordlist is spelling_word_list_filename. See http://sphinxcontrib-spelling.readthedocs.org/en/latest/customize.html#input-options.

By the way, I think it'd be useful to explicitely set spelling_lang to en_US inthe configuration too (it's the default but that's not immediately obvious to a potential contributor).

@beregond

@bmispelon yeah, I found that option earlier, but I'm confused which location should I choose, I've ended up with just spelling_wordlist (without .txt suffix Sphinx doesn't care about this file). And also I've added this spelling_lang.

@timgraham done, thx for this. About documentation - there is some, but please check if it is all you need, or should I change something.

@timgraham
Owner

merged in a0f2525, thanks.

@timgraham timgraham closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 22, 2014
  1. @beregond

    Added spell checker.

    beregond authored
Commits on Feb 23, 2014
  1. @beregond

    Improved spell checker.

    beregond authored
Commits on Feb 25, 2014
  1. @beregond

    Fixed spelling wordlist.

    beregond authored
Commits on Mar 5, 2014
  1. @beregond
This page is out of date. Refresh to see the latest.
View
8 docs/Makefile
@@ -37,6 +37,8 @@ help:
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
+ @echo " spelling to check for typos in documentation"
+
clean:
-rm -rf $(BUILDDIR)/*
@@ -143,3 +145,9 @@ doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
+
+spelling:
+ $(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) $(BUILDDIR)/spelling
+ @echo
+ @echo "Check finished. Wrong words can be found in " \
+ "$(BUILDDIR)/spelling/output.txt."
View
11 docs/conf.py
@@ -33,6 +33,17 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ["djangodocs", "sphinx.ext.intersphinx"]
+# Spelling check needs additional module, that is not installed by default.
+# It is added dynamically, so you can always generate docs.
+if 'spelling' in sys.argv:
+ extensions.append("sphinxcontrib.spelling")
+
+# Spelling language.
+spelling_lang = 'en_US'
+
+# Location of word list.
+spelling_word_list_filename = 'spelling_wordlist'
+
# Add any paths that contain templates here, relative to this directory.
# templates_path = []
View
25 docs/internals/contributing/writing-documentation.txt
@@ -348,3 +348,28 @@ look better:
(that's a tilde) to get just the "last bit" of that path. So
``:class:`~django.contrib.contenttypes.models.ContentType``` will just
display a link with the title "ContentType".
+
+Spelling check
+--------------
+
+Before you commit your docs there you may (and you should) check if in your work
+there are no typos. To do so you have to fulfill some requirements:
+
+* Install ``pyenchant`` package (you will need to have ``enchant`` installed on
+ your system). See: http://pythonhosted.org/pyenchant/ for more info.
+
+* Install ``sphinxcontrib-spelling`` package.
+
+* Change working directory to ``docs`` and run ``make spelling``.
+
+Wrong words (if any) with path and line numbers will be saved into
+``_build/spelling/output.txt``.
+
+If you encounter problem with words you can either:
+
+* Fix typo, surround brand/technology names with double ` or find
+ synonyms for problematic words (preferable).
+
+* If, and only if, you are sure word you are using is correct - add word
+ as correct to ``docs/spelling_wordlist`` (please keep alphabetical
+ order there and write one word per line).
View
727 docs/spelling_wordlist
@@ -0,0 +1,727 @@
+Aalto
+accessor
+Aceh
+actionnable
+addslashes
+admin
+admindocs
+admins
+aggregator
+Ai
+Alchin
+amet
+Anssi
+apnumber
+Apolloner
+app
+appname
+apps
+architected
+arg
+args
+assistive
+attr
+auth
+autoclobber
+autocommit
+autoconf
+autodetect
+autodetectable
+autodetection
+autodetector
+autodiscovery
+autoescape
+autoescaping
+autogenerated
+autoincrement
+autoreload
+Aymeric
+backend
+backends
+backport
+backported
+backports
+backtraces
+basename
+bbcontains
+bboverlaps
+Bcc
+BCC'ed
+bcrypt
+Bcrypt
+beatles
+Beaven
+Berners
+Biggs
+Bjørn
+blocktrans
+blog
+Boersma
+boilerplatish
+Bokmål
+bolded
+bookmarklets
+Bookmarklets
+bpython
+Bronn
+bugfix
+bugfixes
+bugfixing
+builtin
+builtins
+Byteorder
+bytestring
+bytestrings
+cacheable
+cachetable
+callables
+camelcase
+camelCase
+capfirst
+changelist
+Changelist
+changepassword
+changeset
+charset
+checkbox
+checkboxes
+checkin
+Checkin
+clearable
+clearsessions
+clickable
+clickjacking
+cms
+codebase
+codec
+collectstatic
+commenter
+commenters
+committer
+committers
+compilemessages
+concat
+conf
+config
+contactdata
+ContentType
+contenttypes
+contrib
+coveredby
+Córdoba
+createcachetable
+createdb
+createsuperuser
+criticals
+cron
+crontab
+crossref
+csrf
+csrfmiddlewaretoken
+css
+csv
+Ctrl
+customizability
+daemonizing
+Danga
+Darussalam
+dat
+databrowse
+Databrowse
+datatype
+datetimes
+dbshell
+de
+deconstruct
+deconstructing
+deepcopy
+deserialization
+deserialize
+deserialized
+deserializer
+deserializing
+Deserializing
+dev
+dict
+dictConfig
+dicts
+dictsort
+dictsortreversed
+diff
+diffsettings
+dirmod
+distro
+divisibleby
+django
+djangojs
+djangonaut
+djangoproject
+dm
+docstring
+docstrings
+doctests
+doctype
+documentational
+dos
+DoS
+downloadable
+Dreamhost
+Dreamweaver
+drilldown
+dropdown
+drupal
+dumpdata
+Dunck
+dwithin
+editability
+Endian
+endswith
+Enero
+escapejs
+esque
+Ess
+Etag
+ETag
+ETags
+exe
+extendible
+fabfile
+fabfiles
+Facebook
+fallback
+fallbacks
+faq
+fastcgi
+FastCGI
+fcgid
+fieldset
+fieldsets
+filesizeformat
+filesystem
+filesystems
+findstatic
+firstof
+flatpage
+Flatpage
+flatpages
+Flatpages
+floatformat
+flup
+followup
+fooapp
+formfield
+formset
+formsets
+formtools
+freenode
+Friedl
+Frysian
+fu
+gdal
+geo
+geoip
+geolibs
+geolocalized
+geolocation
+geoquerysets
+geospatial
+Geospatial
+Gettext
+GiB
+gid
+gis
+github
+globalization
+google
+Googol
+Graz
+Greenhill
+grey
+gte
+gunicorn
+Gunicorn
+gz
+GZip
+hackish
+handheld
+hardcode
+hardcoded
+hardcoding
+hashable
+hashers
+headerlist
+Hoerner
+Holovaty
+Homebrew
+honeypot
+Honza
+hostname
+hostnames
+howto
+html
+http
+https
+hyperlinks
+icontains
+Idan
+ie
+iendswith
+ies
+iexact
+ifchanged
+ifequal
+ifnotequal
+iframe
+inbox
+Incompliance
+indices
+ing
+ini
+init
+inline
+inlines
+inspectdb
+intcomma
+internet
+intranet
+intword
+ip
+ipsum
+Ipsum
+IPv
+IPython
+irc
+iregex
+iriencode
+ise
+isnull
+iso
+istartswith
+iterable
+iterables
+itunes
+iTunes
+ize
+Jannis
+javascript
+jQuery
+JServ
+Julien
+jython
+Kääriäinen
+keyservers
+KiB
+kilometre
+Kocherhans
+Koziarski
+Král
+kwarg
+kwargs
+Kyngesburye
+latin
+Lawrence
+lexer
+lhs
+lifecycle
+lifecycles
+lighttpd
+linebreaks
+linebreaksbr
+linenumbers
+linestring
+Livni
+ljust
+loaddata
+localdomain
+localflavor
+localflavors
+localhost
+localizable
+localtime
+lorem
+lt
+lte
+Magee
+makemessages
+makemigrations
+Mapnik
+MBR
+memcache
+memcached
+mentorship
+mercator
+metaclass
+metaclasses
+metadata
+metre
+MiB
+micrometre
+middleware
+middlewares
+migrationname
+millimetre
+Minification
+Mispelon
+mixin
+mixins
+modelforms
+modelformset
+modwsgi
+monkeypatched
+Montréal
+multijoins
+multiline
+multipart
+multipolygon
+multithreaded
+multithreading
+Mumbai
+myapp
+myproject
+mysite
+mysql
+naïve
+namespace
+namespaced
+Namespaced
+namespaces
+namespacing
+Nanggroe
+naturalday
+naturaltime
+nd
+needsinfo
+neuroscientist
+newforms
+nginx
+nonspatial
+nullable
+OAuth
+offline
+OGC
+OGR
+ogrinspect
+oldforms
+online
+orderable
+O'Reilly
+org
+Orléans
+orm
+outbox
+Outdim
+outfile
+paginator
+Palau
+params
+parens
+pdf
+perl
+permalink
+pessimization
+Peucker
+pgAdmin
+php
+pickleable
+picosecond
+PIL
+pingback
+pingbacks
+Pinney
+plaintext
+plugin
+plugins
+po
+podcast
+popup
+postgis
+postgres
+Postgres
+postgresql
+pq
+pre
+preconfigured
+prefetch
+prefetched
+prefetching
+prefork
+preforked
+prepend
+prepended
+prepending
+prepopulate
+prepopulated
+prepopulates
+preprocess
+programmatically
+projectname
+proxied
+proxying
+pseudocode
+psycopg
+Puthraya
+py
+pyformat
+Pygments
+pysqlite
+pythonic
+Pythonista
+pytz
+qs
+Québec
+queryset
+querysets
+Querysets
+querystring
+Quickstart
+quoteless
+Radziej
+rc
+rebase
+rebased
+rebasing
+recomputation
+refactor
+refactored
+refactorings
+refactors
+referer
+regex
+regexes
+reimplement
+reindex
+removetags
+repo
+reprojection
+reraise
+reST
+reStructuredText
+reupload
+Reusability
+revalidate
+rhs
+rjust
+roadmap
+Roald
+rss
+runfcgi
+runnning
+runserver
+safeseq
+Sandvik
+savepoint
+savepoints
+Schaub
+screencast
+screencasts
+screenshot
+screenshots
+sdist
+semimajor
+semiminor
+serializable
+serializer
+serializers
+sessionid
+setuptools
+sha
+shapefile
+shapefiles
+sharding
+sid
+simultaneously
+sitemap
+sitemaps
+sitewide
+slashdot
+sliceable
+slippy
+slugify
+solaris
+Solr
+spaceless
+spam
+spammers
+spatialite
+Springmeyer
+sql
+sqlall
+sqlclear
+sqlcustom
+sqldropindexes
+sqlflush
+sqlindexes
+sqlmigrate
+sqlsequencereset
+ssi
+stacktrace
+startapp
+startproject
+startswith
+stateful
+staticfile
+staticfiles
+stderr
+stdlib
+stdout
+stringformat
+striptags
+Stufft
+stylesheet
+stylesheets
+subclass
+subclassed
+subclassing
+subdir
+subdomain
+subdomains
+sublanguage
+subminor
+subpackage
+subpackages
+subqueries
+subquery
+subselect
+subtemplate
+subtemplates
+subviews
+subwidgets
+symlink
+symlinking
+symlinks
+syncdb
+sysadmin
+systemwide
+tablespace
+tablespaces
+tagline
+Tamlyn
+tarball
+tarballs
+Tastypie
+teardown
+templatability
+templatetag
+templating
+testcase
+testserver
+textarea
+Thejaswi
+timedelta
+timeframe
+timeline
+timelines
+timesaving
+timesince
+timestamp
+timeuntil
+titlecase
+tmp
+toolbar
+toolset
+trac
+Transifex
+Tredinnick
+triager
+triagers
+truncatechars
+truncatewords
+tv
+txt
+tz
+ubuntu
+Ubuntuusers
+ul
+umask
+unapply
+unapplying
+uncheck
+unclaim
+uncopyable
+unescape
+unescaped
+ungrouped
+unhandled
+unharmful
+unicode
+uninstall
+uninstalling
+uninstalls
+uniterated
+unittest
+unittests
+unlocalize
+unmigrated
+unparseable
+unpickle
+unpickled
+unpythonic
+unregistration
+unrendered
+Unreviewed
+unsanitized
+unsets
+untar
+url
+urlencode
+urlize
+urlizetrunc
+urljoins
+urllib
+urlpatterns
+urls
+useable
+username
+usernames
+utc
+UTF
+util
+utils
+uwsgi
+uWSGI
+validator
+validators
+validsite
+VARCHAR
+variadic
+vendored
+vendorname
+versioned
+versioning
+vertices
+virtualenv
+virtualized
+Votizen
+webapps
+webdesign
+webkit
+Webkit
+Weblog
+webpages
+webserver
+webservers
+whatsnext
+whitelist
+whitelisted
+whitespaces
+whizbang
+widthratio
+wiki
+wikipedia
+wildcard
+wildcards
+Willison
+Wittams
+wontfix
+wordcount
+wordwrap
+workflow
+worksforme
+wsgi
+www
+xe
+xgettext
+xref
+xxxxx
+yesno
+Zope
Something went wrong with that request. Please try again.