README.md

gwadoc

This package has two main uses:

1. To provide user-facing documentation of things like relations and parts of speech used by wordnets.
2. To provide a Python API for querying this documentation, such as for retrieving the localized name or definition for specific relations.

Installation

You can use pip to install gwadoc (use of a virtual environment is strongly recommended; see here). The minimum Python version is 3.5. As gwadoc is not on PyPI, you can give the GitHub URL to pip:

~$ pip install git+git://github.com/globalwordnet/gwadoc.git

... or clone the repository and install from your local copy:

~$ git clone https://github.com/globalwordnet/gwadoc.git
~$ cd gwadoc/
~/gwadoc$ pip install .

To mark gwadoc as a dependency for your project, just put the git+git://github.com/globalwordnet/gwadoc.git URL in your requirements.txt file or the appropriate place in your setup.py file.

To install the requirements for building the documentation, use the [build] extra. For example, when installing from a local copy:

~/gwadoc$ pip install .[build]

Usage

To use gwadoc in your Python code Then you can use it like this:

>>> import gwadoc
>>> for relname in gwadoc.RELATIONS[:5]:
...     print(relname, '\n   ', gwadoc.relations[relname].df.en)
... 
constitutive
    Core semantic relations that define synsets
hyponym
    a word that is more specific than a given word
hypernym
    a word that is more general than a given word
instance_hyponym
    an occurrence of something
instance_hypernym
    the type of an instance

Where gwadoc.RELATIONS is the inventory of relation names, and gwadoc.relations is the data structure containing documentation about each relation. For each relation, there are several fields:

Field	Description	Comments
df	short definition	Suitable for use in a mouseover
ex	short example	Suitable for use in a mouseover
dfn	long definition
exe	more examples
fa	formal attributes
name	relation name
proj	project-specific names
test	linguistic tests	Probably language specific

For the formal attributes and project names that are available, see gwadoc.inventories. The data structure may be accessed (and defined) using dot-notation or index-notation:

>>> print(gwadoc.relations.hypernym.name)
Hypernym
>>> print(gwadoc.relations['hypernym']['name'])
Hypernym

String fields, such as df, ex, name, test, etc. use the gwadoc.base.MultiString class (see gwadoc.base) so that projects may provide these fields in their own language. The language may be requested directly, or the default language may be specified by calling the gwadoc.set_preferred_language() function:

>>> gwadoc.relations.hypernym.name
<MultiString (Hypernym)>
>>> gwadoc.relations.hypernym.name.ja
'上位語'
>>> gwadoc.set_preferred_language('ja')
>>> gwadoc.relations.hypernym.name
<MultiString (上位語)>

Building the Documentation

After installing the requirements, you can build the HTML documentation:

~/gwadoc$ python docs/build.py html > docs/index.html

Note: if you installed the requirements in a virtual environment make sure you activate it before building the documentation.

Contributing

Please add to the documentation using restructured text in the files in the gwadoc directory. doc-en.py is the most complete at the moment, use the entries for hypernym/hyponym as good examples.

License

Global Wordnet Association Documentation by GWA Documentation Working Group is licensed under a Creative Commons Attribution 4.0 International License.