pylode 2.13.2__tar.gz → 3.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. pyLODE-3.0.1/LICENSE +29 -0
  2. pyLODE-3.0.1/PKG-INFO +324 -0
  3. pyLODE-3.0.1/README.rst +292 -0
  4. pyLODE-3.0.1/pyLODE.egg-info/PKG-INFO +324 -0
  5. pyLODE-3.0.1/pyLODE.egg-info/SOURCES.txt +18 -0
  6. pyLODE-3.0.1/pyLODE.egg-info/requires.txt +3 -0
  7. pyLODE-3.0.1/pylode/__init__.py +7 -0
  8. pyLODE-3.0.1/pylode/__main__.py +6 -0
  9. pyLODE-3.0.1/pylode/cli.py +72 -0
  10. pyLODE-3.0.1/pylode/ontdoc.py +685 -0
  11. {pyLODE-2.13.2/pylode/style → pyLODE-3.0.1/pylode}/pylode.css +80 -6
  12. pyLODE-3.0.1/pylode/rdf_elements.py +132 -0
  13. pyLODE-3.0.1/pylode/utils.py +863 -0
  14. pyLODE-3.0.1/pylode/version.py +1 -0
  15. pyLODE-3.0.1/setup.py +60 -0
  16. pyLODE-2.13.2/LICENSE +0 -643
  17. pyLODE-2.13.2/PKG-INFO +0 -880
  18. pyLODE-2.13.2/README.rst +0 -848
  19. pyLODE-2.13.2/pyLODE.egg-info/PKG-INFO +0 -880
  20. pyLODE-2.13.2/pyLODE.egg-info/SOURCES.txt +0 -80
  21. pyLODE-2.13.2/pyLODE.egg-info/requires.txt +0 -4
  22. pyLODE-2.13.2/pylode/__init__.py +0 -15
  23. pyLODE-2.13.2/pylode/cli.py +0 -217
  24. pyLODE-2.13.2/pylode/common.py +0 -227
  25. pyLODE-2.13.2/pylode/curies.py +0 -2208
  26. pyLODE-2.13.2/pylode/profiles/__init__.py +0 -5
  27. pyLODE-2.13.2/pylode/profiles/base.py +0 -587
  28. pyLODE-2.13.2/pylode/profiles/nmpf.py +0 -1331
  29. pyLODE-2.13.2/pylode/profiles/ontdoc.py +0 -1442
  30. pyLODE-2.13.2/pylode/profiles/prof.py +0 -274
  31. pyLODE-2.13.2/pylode/profiles/profile.py +0 -158
  32. pyLODE-2.13.2/pylode/profiles/vocpub.py +0 -639
  33. pyLODE-2.13.2/pylode/server.py +0 -60
  34. pyLODE-2.13.2/pylode/templates/agent.html +0 -11
  35. pyLODE-2.13.2/pylode/templates/agent.md +0 -11
  36. pyLODE-2.13.2/pylode/templates/namespaces.html +0 -11
  37. pyLODE-2.13.2/pylode/templates/namespaces.md +0 -7
  38. pyLODE-2.13.2/pylode/templates/nmpf/class.html +0 -131
  39. pyLODE-2.13.2/pylode/templates/nmpf/class.md +0 -43
  40. pyLODE-2.13.2/pylode/templates/nmpf/classes.html +0 -11
  41. pyLODE-2.13.2/pylode/templates/nmpf/classes.md +0 -7
  42. pyLODE-2.13.2/pylode/templates/nmpf/document.html +0 -45
  43. pyLODE-2.13.2/pylode/templates/nmpf/document.md +0 -16
  44. pyLODE-2.13.2/pylode/templates/nmpf/metadata.html +0 -127
  45. pyLODE-2.13.2/pylode/templates/nmpf/metadata.md +0 -111
  46. pyLODE-2.13.2/pylode/templates/nmpf/named_individual.html +0 -97
  47. pyLODE-2.13.2/pylode/templates/nmpf/named_individual.md +0 -37
  48. pyLODE-2.13.2/pylode/templates/nmpf/named_individuals.html +0 -11
  49. pyLODE-2.13.2/pylode/templates/nmpf/named_individuals.md +0 -7
  50. pyLODE-2.13.2/pylode/templates/nmpf/properties.html +0 -65
  51. pyLODE-2.13.2/pylode/templates/nmpf/properties.md +0 -45
  52. pyLODE-2.13.2/pylode/templates/nmpf/property.html +0 -129
  53. pyLODE-2.13.2/pylode/templates/nmpf/property.md +0 -37
  54. pyLODE-2.13.2/pylode/templates/ontdoc/class.html +0 -134
  55. pyLODE-2.13.2/pylode/templates/ontdoc/class.md +0 -43
  56. pyLODE-2.13.2/pylode/templates/ontdoc/classes.html +0 -11
  57. pyLODE-2.13.2/pylode/templates/ontdoc/classes.md +0 -7
  58. pyLODE-2.13.2/pylode/templates/ontdoc/document.html +0 -43
  59. pyLODE-2.13.2/pylode/templates/ontdoc/document.md +0 -16
  60. pyLODE-2.13.2/pylode/templates/ontdoc/metadata.html +0 -127
  61. pyLODE-2.13.2/pylode/templates/ontdoc/metadata.md +0 -111
  62. pyLODE-2.13.2/pylode/templates/ontdoc/named_individual.html +0 -65
  63. pyLODE-2.13.2/pylode/templates/ontdoc/named_individual.md +0 -25
  64. pyLODE-2.13.2/pylode/templates/ontdoc/named_individuals.html +0 -13
  65. pyLODE-2.13.2/pylode/templates/ontdoc/named_individuals.md +0 -7
  66. pyLODE-2.13.2/pylode/templates/ontdoc/properties.html +0 -65
  67. pyLODE-2.13.2/pylode/templates/ontdoc/properties.md +0 -45
  68. pyLODE-2.13.2/pylode/templates/ontdoc/property.html +0 -143
  69. pyLODE-2.13.2/pylode/templates/ontdoc/property.md +0 -37
  70. pyLODE-2.13.2/pylode/templates/orcid.html +0 -21
  71. pyLODE-2.13.2/pylode/templates/orcid.md +0 -1
  72. pyLODE-2.13.2/pylode/templates/prof/prof.html +0 -41
  73. pyLODE-2.13.2/pylode/templates/prof/prof.md +0 -16
  74. pyLODE-2.13.2/pylode/templates/prof/profile.html +0 -90
  75. pyLODE-2.13.2/pylode/templates/prof/profile.md +0 -85
  76. pyLODE-2.13.2/pylode/templates/prof/resource_descriptor.html +0 -49
  77. pyLODE-2.13.2/pylode/templates/prof/resource_descriptor.md +0 -21
  78. pyLODE-2.13.2/pylode/templates/vocpub/collection.html +0 -51
  79. pyLODE-2.13.2/pylode/templates/vocpub/collection.md +0 -23
  80. pyLODE-2.13.2/pylode/templates/vocpub/collections.html +0 -11
  81. pyLODE-2.13.2/pylode/templates/vocpub/collections.md +0 -7
  82. pyLODE-2.13.2/pylode/templates/vocpub/concept.html +0 -115
  83. pyLODE-2.13.2/pylode/templates/vocpub/concept.md +0 -40
  84. pyLODE-2.13.2/pylode/templates/vocpub/concept_hierarchy.html +0 -80
  85. pyLODE-2.13.2/pylode/templates/vocpub/concept_scheme.html +0 -105
  86. pyLODE-2.13.2/pylode/templates/vocpub/concept_scheme.md +0 -102
  87. pyLODE-2.13.2/pylode/templates/vocpub/concepts.html +0 -9
  88. pyLODE-2.13.2/pylode/templates/vocpub/concepts.md +0 -7
  89. pyLODE-2.13.2/pylode/templates/vocpub/taxonomy.html +0 -45
  90. pyLODE-2.13.2/pylode/templates/vocpub/taxonomy.md +0 -17
  91. pyLODE-2.13.2/setup.py +0 -68
  92. {pyLODE-2.13.2 → pyLODE-3.0.1}/pyLODE.egg-info/dependency_links.txt +0 -0
  93. {pyLODE-2.13.2 → pyLODE-3.0.1}/pyLODE.egg-info/entry_points.txt +0 -0
  94. {pyLODE-2.13.2 → pyLODE-3.0.1}/pyLODE.egg-info/top_level.txt +0 -0
  95. {pyLODE-2.13.2 → pyLODE-3.0.1}/setup.cfg +0 -0
pyLODE-3.0.1/LICENSE ADDED
@@ -0,0 +1,29 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2002-2021, RDFLib Team
4
+ All rights reserved.
5
+
6
+ Redistribution and use in source and binary forms, with or without
7
+ modification, are permitted provided that the following conditions are met:
8
+
9
+ 1. Redistributions of source code must retain the above copyright notice, this
10
+ list of conditions and the following disclaimer.
11
+
12
+ 2. Redistributions in binary form must reproduce the above copyright notice,
13
+ this list of conditions and the following disclaimer in the documentation
14
+ and/or other materials provided with the distribution.
15
+
16
+ 3. Neither the name of the copyright holder nor the names of its
17
+ contributors may be used to endorse or promote products derived from
18
+ this software without specific prior written permission.
19
+
20
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
pyLODE-3.0.1/PKG-INFO ADDED
@@ -0,0 +1,324 @@
1
+ Metadata-Version: 2.1
2
+ Name: pyLODE
3
+ Version: 3.0.1
4
+ Summary: An OWL ontology documentation tool using Python and templating, based on LODE.
5
+ Home-page: https://github.com/rdflib/pyLODE
6
+ Author: Nicholas J. Car
7
+ Author-email: nicholas.car@surroundaustralia.com
8
+ License: LICENSE
9
+ Download-URL: https://github.com/RDFLib/pyLODE/releases/tag/3.0.1
10
+ Project-URL: Bug Reports, https://github.com/rdflib/pyLODE/issues
11
+ Project-URL: Source, https://github.com/rdflib/pyLODE/
12
+ Keywords: Semantic Web,OWL,ontology,template,HTML,documentation
13
+ Platform: UNKNOWN
14
+ Classifier: Development Status :: 5 - Production/Stable
15
+ Classifier: Topic :: Utilities
16
+ Classifier: License :: OSI Approved :: BSD License
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: Natural Language :: English
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Programming Language :: Python :: 3.7
22
+ Classifier: Programming Language :: Python :: 3.8
23
+ Classifier: Programming Language :: Python :: 3.9
24
+ Classifier: Programming Language :: Python :: 3.10
25
+ Classifier: Programming Language :: Python :: Implementation :: CPython
26
+ Classifier: Programming Language :: Python :: Implementation :: PyPy
27
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
28
+ Description-Content-Type: text/x-rst
29
+ License-File: LICENSE
30
+
31
+ .. image:: https://rawcdn.githack.com/RDFLib/pyLODE/b1ff1b1e19262cdc21ee28c7362b1690ca18e30b/img/pyLODE-250.png
32
+
33
+ .. image:: https://badge.fury.io/py/pyLODE.svg
34
+ :target: https://badge.fury.io/py/pyLODE
35
+
36
+ pyLODE
37
+ ******
38
+ An OWL ontology documentation tool using Python, based on LODE.
39
+
40
+ In addition to making web page, human-readable forms of ontologies, pyLODE encourages ontology annotation *best
41
+ practice* by only producing good results for well documented inputs! pyLODE defines what it considers 'well documented'
42
+ in sections below, e.g. `What pyLODE understands`_.
43
+
44
+ ----
45
+
46
+ **A note on the v 3.x change**
47
+
48
+ *This is pyLODE version 3.0.1 and it's vastly different from pyLODE 2.x. It doesn't yet handle all the various "profiles" that pyLODE 2.13.2 does, such as SKOS 'vocabularies' & Profiles Vocabulary 'profiles', it only handles OWL 'ontologies', nor all the special data types, such as JSON literals, BUT, it generates HTML in a much more straightforward manner and the code is both more efficient and much more maintainable, which is why it's been made.*
49
+
50
+ *v 3.x will eventually catch up to all of v 2.13.2's features.*
51
+
52
+ *To access v 2.13.2 of pyLODE, either `download it from PyPI <https://pypi.org/project/pyLODE/2.13.2/>`_, `check it out from GitHub <https://github.com/RDFLib/pyLODE/releases/tag/2.13.2>`_ or access it via the `online service <http://pylode.surroundaustralia.com/>`_.*
53
+
54
+ ----
55
+
56
+ Contents
57
+ ========
58
+ 1. `Quick Intro`_
59
+ 2. Use_
60
+ 3. `What pyLODE understands`_
61
+ 4. Examples_
62
+ 5. Installation_
63
+ 6. `Differences from LODE`_
64
+ 7. `Releases`_
65
+ 8. License_
66
+ 9. Citation_
67
+ 10. Collaboration_
68
+ 11. Contacts_
69
+
70
+
71
+ Quick Intro
72
+ ===========
73
+ The Live OWL Documentation Environment tool
74
+ (`LODE <https://github.com/essepuntato/LODE>`__) is a well-known (in
75
+ Semantic Web circles) Java & XSLT-based tool used to generate
76
+ human-readable HTML documents for OWL and RDF ontologies. That tool is
77
+ now a bit dated (old-style HTML, use of older technologies like XSLT)
78
+ and it's (`online version <https://www.essepuntato.it/lode>`__) is not always
79
+ online.
80
+
81
+ This tool is a complete re-implementation of LODE's functionality using
82
+ Python and Python's RDF manipulation module,
83
+ `rdflib <https://pypi.org/project/rdflib/>`__. An ontology to be
84
+ documented is parsed and inspected using rdflib and HTML is generated
85
+ directly, using Python's `dominate <https://pypi.org/project/dominate/>`__
86
+ package.
87
+
88
+ Use
89
+ ===
90
+
91
+ The tool can be used in multiple ways:
92
+
93
+ - BASH command line script
94
+ - pyLODE.sh in bin/
95
+ - Windows EXE
96
+ - pyLODE.exe in bin/
97
+ - Mac executable
98
+ - pyLODE in bin/
99
+ - Python Script
100
+ - cli.py or module
101
+ - as-a-service locally
102
+ - via the popular `Falcon framework <https://falconframework.org/>`__.
103
+ - see server.py in the main folder
104
+ - as-a-service online
105
+ - hosted at https://pylode.surroundaustralia.com
106
+
107
+ Command line arguments
108
+ ----------------------
109
+
110
+ The BASH, Windows EXE and Python Script methods all use the same command line
111
+ arguments:
112
+
113
+ ::
114
+
115
+ usage: cli.py [-h] [-v] [-o OUTPUTFILE] [-c {true,false}] input
116
+
117
+ positional arguments:
118
+ input Input file location or URL
119
+
120
+ optional arguments:
121
+ -h, --help show this help message and exit
122
+ -v, --version show program's version number and exit
123
+ -o OUTPUTFILE,
124
+ --outputfile OUTPUTFILE
125
+ A name you wish to assign to the output file. Will be
126
+ postfixed with .html if not already added. If no
127
+ output file is given, output will be printed to screen
128
+ -c {true,false},
129
+ --css {true,false}
130
+ Whether (true) or not (false) to include CSS within an
131
+ output HTML file.
132
+
133
+ Basic Use
134
+ ^^^^^^^^^
135
+
136
+ * as a Python script
137
+ * executed in this directory
138
+
139
+ ::
140
+
141
+ python pylode examples/minimal.ttl -o minimal.html
142
+
143
+ This will produce the file ``minimal.html`` in this directory which should
144
+ match exactly the file ``examples/minimal.html``.
145
+
146
+
147
+ Examples
148
+ ========
149
+
150
+ The `examples/ directory <https://github.com/RDFLib/pyLODE/tree/master/examples>`_
151
+ contains multiple pairs of RDF & HTML files generated from them using this
152
+ version of pyLODE.
153
+
154
+ You can also see rendered versions of these example files online too:
155
+
156
+ * `minimal.html <http://rdflib.dev/pyLODE/examples/ontdoc/minimal.html>`_
157
+ * `agift.html <http://rdflib.dev/pyLODE/examples/ontdoc/agift.html>`_
158
+ * `alternates.html <http://rdflib.dev/pyLODE/examples/ontdoc/alternates.html>`_
159
+ * `asgs.html <http://rdflib.dev/pyLODE/examples/ontdoc/asgs.html>`_
160
+
161
+
162
+ What pyLODE understands
163
+ =======================
164
+
165
+ pyLODE knows about definitional ontologies (``owl:Ontology``) and the major
166
+ elements usually fount in them, such as classes (``owl:Class`` or ``rdf:Class)
167
+ and properties (``rdf:Property`` & ``owl:ObjectProperty`` etc.).
168
+
169
+ To see what properties for ontology, class and RDF property documentation
170
+ pyLODE currently supports, just look in the ``rdf_elements.py`` file. All
171
+ elements' properties supported are given in property lists there.
172
+
173
+ pyLODES won't just translate everything that you can describe in RDF into
174
+ HTML! This is a conscious design choice to ensure that a certain conventional
175
+ style of documented ontology is produced. However, surrport for new
176
+ properties and ontology patterns can be made - just create an Issue on
177
+ `this project's Issue tracker <https://github.com/RDFLib/pyLODE/issues>`__.
178
+
179
+ While it *does* know about instance data, such as Named Individuals, it's
180
+ not really designed to document large ontologies containing class instances.
181
+
182
+ Notes on Agents
183
+ ---------------
184
+ pyLODE can understand both simple and complex Agent objects. You can use
185
+ simple string properties like ``dc:contributor "Nicholas J. Car"`` too if
186
+ you really must but better would be to take advantage of real Linked Data
187
+ representation, e.g. complex Agent objects with web addresses, emails,
188
+ affiliations, ORCIDs and so on, e.g.:
189
+
190
+ ::
191
+
192
+ <ontology_x>
193
+ dct:creator [
194
+ sdo:name "Nicholas J. Car" ;
195
+ sdo:identifier <http://orcid.org/0000-0002-8742-7730> ;
196
+ sdo:affiliation [
197
+ sdo:name "SURROUND Australia Pty Ldt." ;
198
+ sdo:url "https://surroundaustralia.com"^^xsd:anyURI ;
199
+ ] ;
200
+ ] ;
201
+
202
+ See all the properties in ``rdf_elements.py:AGENT_PROPS`` for a list of
203
+ all the Agent properties pyLODE can handle.
204
+
205
+ Installation
206
+ ============
207
+
208
+ pyLODE is `on PyPI <https://pypi.org/project/pyLODE/>`_, so you can install
209
+ it using `pip <https://pypi.org/project/pip/>`_ as normal:
210
+
211
+ ::
212
+
213
+ pip install pylode
214
+
215
+
216
+ Differences from LODE
217
+ =====================
218
+ - command line access
219
+
220
+ - you can use this on your own desktop so you don't need me to
221
+ maintain a live service for use
222
+
223
+ - use of modern simple HTML
224
+
225
+ - no JavaScript: pyLODE generates static HTML pages
226
+
227
+ - catering for a wider range of ontology options such as:
228
+
229
+ - schema.org ``domainIncludes`` & ``rangeIncludes`` for properties
230
+
231
+ - better Agent representation
232
+
233
+ - see the `Notes on Agents`_ section above
234
+
235
+ - smarter CURIES
236
+
237
+ - pyLODE caches and looks up well-known prefixes to make more/better
238
+ CURIES
239
+ - it tries to be smart with CURIE presentation by CURIE-ising all
240
+ URIs it finds, rather than printing them
241
+
242
+ - reference ontologies property labels
243
+
244
+ - pyLODE caches ~ 10 well-known ontologies (RDFS, SKOS etc), properties from which people often use for their ontology documentation. Where these properties are used, the background ontology's labels are use
245
+
246
+ - **active development**
247
+
248
+ - pyLODE has been under active development since mid-2019 and is
249
+ still very much actively developed - it's not just staying still
250
+ - it will be improved in foreseeable to cater for more and more things
251
+ - recent ontology documentation initiatives such as the `MOD
252
+ Ontology <https://github.com/sifrproject/MOD-Ontology>`__ will be
253
+ handled, if requested
254
+
255
+
256
+ Releases
257
+ ========
258
+ pyLODE is under continual and constant development. The current developers have a roadmap for enhancements in mind,
259
+ which is given here, however, since this is an open source project, new developers may join the pyLODE dev community
260
+ and change/add development priorities.
261
+
262
+ Current Release
263
+ ---------------
264
+
265
+ The current release, as of January, 2022, is **3.0.1**.
266
+
267
+ Release Schedule
268
+ ----------------
269
+
270
+ .. csv-table:: **pyLODE Release Schedule**
271
+ :header: "Version", "Date", "Description"
272
+ :widths: 15, 10, 30
273
+
274
+ **3.0.1**, **6 Jan 2022**, "**Direct HTML generation using dominate; easier to maintain and extend**"
275
+ 2.13.2, 21 December 2021, "Updated RDFlib to 6.1.1, improved test to properly use pytest"
276
+ 2.10.0, 24 May 2021, "Update Windows EXE build process, simplified versioning"
277
+ 2.9.1, 28 Apr 2021, "Support for ASCIIDOC format (OntDoc profile only)"
278
+ 2.8.11, 28 Apr 2021, "Further changes for PyPI only"
279
+ 2.8.10, 27 Apr 2021, "Further changes for PyPI only"
280
+ 2.8.9, 27 Apr 2021, "PyPI enhancements only"
281
+ 2.8.8, 27 Apr 2021, "Several small bugs fixed, auto-generation of version no. from Git tag"
282
+ 2.8.6, 23 Feb 20201, "Fixing char encoding issues, updated examples, new test files style - per issue"
283
+ 2.8.5, 5 Jan 20201, "Small enhancements to the Falcon server deployment option"
284
+ 2.8.3, 3 July 2020, "Packaging bugfixes only"
285
+ 2.7, 1 July 2020, "Much refactoring for new profile creation ease"
286
+ 2.6, June 2020, "Supports PROF profiles as well as taxonomies & ontologies"
287
+ 2.4, 27 May 2020, "Small improvements over 2.0"
288
+ 2.0, 18 Apr 2020, "Includes multiple profiles - OWP & vocpub"
289
+ 1.0, 15 Dec 2019, "Initial working release"
290
+
291
+
292
+ License
293
+ =======
294
+ This code is licensed using the BSD 3-Clause licence. See the `LICENSE
295
+ file <LICENSE>`_ for the deed. Note *Citation* below though for
296
+ attribution.
297
+
298
+
299
+ Citation
300
+ ========
301
+ If you use pyLODE, please leave the pyLODE logo with a hyperlink back
302
+ here in the top left of published HTML pages.
303
+
304
+
305
+ Collaboration
306
+ =============
307
+ The maintainers welcome any collaboration.
308
+
309
+ If you have suggestions, please email the contacts below or leave Issues
310
+ in this repository's `Issue tracker <https://github.com/rdflib/pyLODE/issues>`_.
311
+
312
+ But the very best thing you could do is create a Pull Request for us to
313
+ action!
314
+
315
+
316
+ Contacts
317
+ ========
318
+ | *Author*:
319
+ | **Nicholas Car**
320
+ | *Data System Architect*
321
+ | `SURROUND Australia Pty Ltd <https://surroundaustralia.com>`_
322
+ | nicholas.car@surroundaustralia.com
323
+
324
+
@@ -0,0 +1,292 @@
1
+ .. image:: https://rawcdn.githack.com/RDFLib/pyLODE/b1ff1b1e19262cdc21ee28c7362b1690ca18e30b/img/pyLODE-250.png
2
+
3
+ .. image:: https://badge.fury.io/py/pyLODE.svg
4
+ :target: https://badge.fury.io/py/pyLODE
5
+
6
+ pyLODE
7
+ ******
8
+ An OWL ontology documentation tool using Python, based on LODE.
9
+
10
+ In addition to making web page, human-readable forms of ontologies, pyLODE encourages ontology annotation *best
11
+ practice* by only producing good results for well documented inputs! pyLODE defines what it considers 'well documented'
12
+ in sections below, e.g. `What pyLODE understands`_.
13
+
14
+ ----
15
+
16
+ **A note on the v 3.x change**
17
+
18
+ *This is pyLODE version 3.0.1 and it's vastly different from pyLODE 2.x. It doesn't yet handle all the various "profiles" that pyLODE 2.13.2 does, such as SKOS 'vocabularies' & Profiles Vocabulary 'profiles', it only handles OWL 'ontologies', nor all the special data types, such as JSON literals, BUT, it generates HTML in a much more straightforward manner and the code is both more efficient and much more maintainable, which is why it's been made.*
19
+
20
+ *v 3.x will eventually catch up to all of v 2.13.2's features.*
21
+
22
+ *To access v 2.13.2 of pyLODE, either `download it from PyPI <https://pypi.org/project/pyLODE/2.13.2/>`_, `check it out from GitHub <https://github.com/RDFLib/pyLODE/releases/tag/2.13.2>`_ or access it via the `online service <http://pylode.surroundaustralia.com/>`_.*
23
+
24
+ ----
25
+
26
+ Contents
27
+ ========
28
+ 1. `Quick Intro`_
29
+ 2. Use_
30
+ 3. `What pyLODE understands`_
31
+ 4. Examples_
32
+ 5. Installation_
33
+ 6. `Differences from LODE`_
34
+ 7. `Releases`_
35
+ 8. License_
36
+ 9. Citation_
37
+ 10. Collaboration_
38
+ 11. Contacts_
39
+
40
+
41
+ Quick Intro
42
+ ===========
43
+ The Live OWL Documentation Environment tool
44
+ (`LODE <https://github.com/essepuntato/LODE>`__) is a well-known (in
45
+ Semantic Web circles) Java & XSLT-based tool used to generate
46
+ human-readable HTML documents for OWL and RDF ontologies. That tool is
47
+ now a bit dated (old-style HTML, use of older technologies like XSLT)
48
+ and it's (`online version <https://www.essepuntato.it/lode>`__) is not always
49
+ online.
50
+
51
+ This tool is a complete re-implementation of LODE's functionality using
52
+ Python and Python's RDF manipulation module,
53
+ `rdflib <https://pypi.org/project/rdflib/>`__. An ontology to be
54
+ documented is parsed and inspected using rdflib and HTML is generated
55
+ directly, using Python's `dominate <https://pypi.org/project/dominate/>`__
56
+ package.
57
+
58
+ Use
59
+ ===
60
+
61
+ The tool can be used in multiple ways:
62
+
63
+ - BASH command line script
64
+ - pyLODE.sh in bin/
65
+ - Windows EXE
66
+ - pyLODE.exe in bin/
67
+ - Mac executable
68
+ - pyLODE in bin/
69
+ - Python Script
70
+ - cli.py or module
71
+ - as-a-service locally
72
+ - via the popular `Falcon framework <https://falconframework.org/>`__.
73
+ - see server.py in the main folder
74
+ - as-a-service online
75
+ - hosted at https://pylode.surroundaustralia.com
76
+
77
+ Command line arguments
78
+ ----------------------
79
+
80
+ The BASH, Windows EXE and Python Script methods all use the same command line
81
+ arguments:
82
+
83
+ ::
84
+
85
+ usage: cli.py [-h] [-v] [-o OUTPUTFILE] [-c {true,false}] input
86
+
87
+ positional arguments:
88
+ input Input file location or URL
89
+
90
+ optional arguments:
91
+ -h, --help show this help message and exit
92
+ -v, --version show program's version number and exit
93
+ -o OUTPUTFILE,
94
+ --outputfile OUTPUTFILE
95
+ A name you wish to assign to the output file. Will be
96
+ postfixed with .html if not already added. If no
97
+ output file is given, output will be printed to screen
98
+ -c {true,false},
99
+ --css {true,false}
100
+ Whether (true) or not (false) to include CSS within an
101
+ output HTML file.
102
+
103
+ Basic Use
104
+ ^^^^^^^^^
105
+
106
+ * as a Python script
107
+ * executed in this directory
108
+
109
+ ::
110
+
111
+ python pylode examples/minimal.ttl -o minimal.html
112
+
113
+ This will produce the file ``minimal.html`` in this directory which should
114
+ match exactly the file ``examples/minimal.html``.
115
+
116
+
117
+ Examples
118
+ ========
119
+
120
+ The `examples/ directory <https://github.com/RDFLib/pyLODE/tree/master/examples>`_
121
+ contains multiple pairs of RDF & HTML files generated from them using this
122
+ version of pyLODE.
123
+
124
+ You can also see rendered versions of these example files online too:
125
+
126
+ * `minimal.html <http://rdflib.dev/pyLODE/examples/ontdoc/minimal.html>`_
127
+ * `agift.html <http://rdflib.dev/pyLODE/examples/ontdoc/agift.html>`_
128
+ * `alternates.html <http://rdflib.dev/pyLODE/examples/ontdoc/alternates.html>`_
129
+ * `asgs.html <http://rdflib.dev/pyLODE/examples/ontdoc/asgs.html>`_
130
+
131
+
132
+ What pyLODE understands
133
+ =======================
134
+
135
+ pyLODE knows about definitional ontologies (``owl:Ontology``) and the major
136
+ elements usually fount in them, such as classes (``owl:Class`` or ``rdf:Class)
137
+ and properties (``rdf:Property`` & ``owl:ObjectProperty`` etc.).
138
+
139
+ To see what properties for ontology, class and RDF property documentation
140
+ pyLODE currently supports, just look in the ``rdf_elements.py`` file. All
141
+ elements' properties supported are given in property lists there.
142
+
143
+ pyLODES won't just translate everything that you can describe in RDF into
144
+ HTML! This is a conscious design choice to ensure that a certain conventional
145
+ style of documented ontology is produced. However, surrport for new
146
+ properties and ontology patterns can be made - just create an Issue on
147
+ `this project's Issue tracker <https://github.com/RDFLib/pyLODE/issues>`__.
148
+
149
+ While it *does* know about instance data, such as Named Individuals, it's
150
+ not really designed to document large ontologies containing class instances.
151
+
152
+ Notes on Agents
153
+ ---------------
154
+ pyLODE can understand both simple and complex Agent objects. You can use
155
+ simple string properties like ``dc:contributor "Nicholas J. Car"`` too if
156
+ you really must but better would be to take advantage of real Linked Data
157
+ representation, e.g. complex Agent objects with web addresses, emails,
158
+ affiliations, ORCIDs and so on, e.g.:
159
+
160
+ ::
161
+
162
+ <ontology_x>
163
+ dct:creator [
164
+ sdo:name "Nicholas J. Car" ;
165
+ sdo:identifier <http://orcid.org/0000-0002-8742-7730> ;
166
+ sdo:affiliation [
167
+ sdo:name "SURROUND Australia Pty Ldt." ;
168
+ sdo:url "https://surroundaustralia.com"^^xsd:anyURI ;
169
+ ] ;
170
+ ] ;
171
+
172
+ See all the properties in ``rdf_elements.py:AGENT_PROPS`` for a list of
173
+ all the Agent properties pyLODE can handle.
174
+
175
+ Installation
176
+ ============
177
+
178
+ pyLODE is `on PyPI <https://pypi.org/project/pyLODE/>`_, so you can install
179
+ it using `pip <https://pypi.org/project/pip/>`_ as normal:
180
+
181
+ ::
182
+
183
+ pip install pylode
184
+
185
+
186
+ Differences from LODE
187
+ =====================
188
+ - command line access
189
+
190
+ - you can use this on your own desktop so you don't need me to
191
+ maintain a live service for use
192
+
193
+ - use of modern simple HTML
194
+
195
+ - no JavaScript: pyLODE generates static HTML pages
196
+
197
+ - catering for a wider range of ontology options such as:
198
+
199
+ - schema.org ``domainIncludes`` & ``rangeIncludes`` for properties
200
+
201
+ - better Agent representation
202
+
203
+ - see the `Notes on Agents`_ section above
204
+
205
+ - smarter CURIES
206
+
207
+ - pyLODE caches and looks up well-known prefixes to make more/better
208
+ CURIES
209
+ - it tries to be smart with CURIE presentation by CURIE-ising all
210
+ URIs it finds, rather than printing them
211
+
212
+ - reference ontologies property labels
213
+
214
+ - pyLODE caches ~ 10 well-known ontologies (RDFS, SKOS etc), properties from which people often use for their ontology documentation. Where these properties are used, the background ontology's labels are use
215
+
216
+ - **active development**
217
+
218
+ - pyLODE has been under active development since mid-2019 and is
219
+ still very much actively developed - it's not just staying still
220
+ - it will be improved in foreseeable to cater for more and more things
221
+ - recent ontology documentation initiatives such as the `MOD
222
+ Ontology <https://github.com/sifrproject/MOD-Ontology>`__ will be
223
+ handled, if requested
224
+
225
+
226
+ Releases
227
+ ========
228
+ pyLODE is under continual and constant development. The current developers have a roadmap for enhancements in mind,
229
+ which is given here, however, since this is an open source project, new developers may join the pyLODE dev community
230
+ and change/add development priorities.
231
+
232
+ Current Release
233
+ ---------------
234
+
235
+ The current release, as of January, 2022, is **3.0.1**.
236
+
237
+ Release Schedule
238
+ ----------------
239
+
240
+ .. csv-table:: **pyLODE Release Schedule**
241
+ :header: "Version", "Date", "Description"
242
+ :widths: 15, 10, 30
243
+
244
+ **3.0.1**, **6 Jan 2022**, "**Direct HTML generation using dominate; easier to maintain and extend**"
245
+ 2.13.2, 21 December 2021, "Updated RDFlib to 6.1.1, improved test to properly use pytest"
246
+ 2.10.0, 24 May 2021, "Update Windows EXE build process, simplified versioning"
247
+ 2.9.1, 28 Apr 2021, "Support for ASCIIDOC format (OntDoc profile only)"
248
+ 2.8.11, 28 Apr 2021, "Further changes for PyPI only"
249
+ 2.8.10, 27 Apr 2021, "Further changes for PyPI only"
250
+ 2.8.9, 27 Apr 2021, "PyPI enhancements only"
251
+ 2.8.8, 27 Apr 2021, "Several small bugs fixed, auto-generation of version no. from Git tag"
252
+ 2.8.6, 23 Feb 20201, "Fixing char encoding issues, updated examples, new test files style - per issue"
253
+ 2.8.5, 5 Jan 20201, "Small enhancements to the Falcon server deployment option"
254
+ 2.8.3, 3 July 2020, "Packaging bugfixes only"
255
+ 2.7, 1 July 2020, "Much refactoring for new profile creation ease"
256
+ 2.6, June 2020, "Supports PROF profiles as well as taxonomies & ontologies"
257
+ 2.4, 27 May 2020, "Small improvements over 2.0"
258
+ 2.0, 18 Apr 2020, "Includes multiple profiles - OWP & vocpub"
259
+ 1.0, 15 Dec 2019, "Initial working release"
260
+
261
+
262
+ License
263
+ =======
264
+ This code is licensed using the BSD 3-Clause licence. See the `LICENSE
265
+ file <LICENSE>`_ for the deed. Note *Citation* below though for
266
+ attribution.
267
+
268
+
269
+ Citation
270
+ ========
271
+ If you use pyLODE, please leave the pyLODE logo with a hyperlink back
272
+ here in the top left of published HTML pages.
273
+
274
+
275
+ Collaboration
276
+ =============
277
+ The maintainers welcome any collaboration.
278
+
279
+ If you have suggestions, please email the contacts below or leave Issues
280
+ in this repository's `Issue tracker <https://github.com/rdflib/pyLODE/issues>`_.
281
+
282
+ But the very best thing you could do is create a Pull Request for us to
283
+ action!
284
+
285
+
286
+ Contacts
287
+ ========
288
+ | *Author*:
289
+ | **Nicholas Car**
290
+ | *Data System Architect*
291
+ | `SURROUND Australia Pty Ltd <https://surroundaustralia.com>`_
292
+ | nicholas.car@surroundaustralia.com