First pass at autogenerating docs

.gitignore

@@ -5,6 +5,8 @@ save/
 *.txt
 !CMakeLists.txt
 *.exe
+docs/api.md
+docs/INDEX.md
 
 # Created by https://www.gitignore.io/api/macos,linux,cmake,windows
 

.travis.yml

@@ -28,3 +28,15 @@ notifications:
   email:
     on_success: change
     on_failure: always
+
+before_deploy:
+  - npm install gitbook-cli -g
+  - cd "${TRAVIS_BUILD_DIR}/docs"
+  - "./make.sh"
+deploy:
+  provider: pages
+  skip-cleanup: true
+  github-token: $GITHUB_TOKEN
+  keep-history: true
+  on:
+    branch: master

README.md

@@ -10,8 +10,6 @@ d2itemreader is a C library for parsing Diablo II character/stash files (`.d2s`,
 
 ## Usage
 
-### Overview
-
 Most API functions in d2itemreader.h work in the following way:
 
 - There is a `<struct>_parse` function that takes a pointer to a struct and returns a `d2err` enum.
@@ -39,6 +37,12 @@ const char *filename = "path/to/file";
 // determine the filetype if it is not known in advance
 enum d2filetype filetype = d2filetype_of_file(filename);
 
+if (filetype != D2FILETYPE_D2_CHARACTER)
+{
+	fprintf(stderr, "File is not a d2 character file: %s\n", filename);
+	return;
+}
+
 size_t bytesRead;
 d2char character;
 d2err err = d2char_parse_file(filename, &character, &bytesRead);
@@ -68,71 +72,6 @@ else
 }
 ```
 
-### API Reference
-
-#### The `d2item` struct
-
-Field | Description
---- | ---
-`bool identified` | 
-`bool socketed` | 
-`bool isNew` | 
-`bool isEar` | 
-`bool starterItem` | 
-`bool simpleItem` | 
-`bool ethereal` | 
-`bool personalized` | 
-`bool isRuneword` | Diablo II does not save any info that *directly* maps an item to a Runes.txt row. Instead, which runeword the item has is determined by the runes socketed in it, and can be checked against Runes.txt's RuneX columns (in order) to determine which row matches the item's runes. *Note: The game performs this sanity check on every runeword item on load, and removes any that are invalid*
-`uint8_t version` | 0 = pre-1.08, 1 = classic, 100 = expansion, 101 = expansion 1.10+
-`uint8_t locationID` | see the d2location enum
-`uint8_t equippedID` | see the d2equiplocation enum
-`uint8_t positionX` | the x coordinate of the item
-`uint8_t positionY` | the y coordinate of the item
-`uint8_t panelID` | the ID of the page the item is on (main inventory, stash, cube, etc); only set if the item's locationID != D2LOCATION_STORED
-`d2ear ear` | only initialized if isEar is true; NOTE: Anything below this will be unitialized when isEar is true
-`char code[]` | null-terminated item code, typical string length is 3-4 characters
-`uint8_t numItemsInSockets` | Number of items that are socketed within this item
-`d2itemlist socketedItems` | List of items socketed within this item
-*NOTE:*` | *All of the following are only set if `simpleItem` is false*
-`uint32_t id` | random unique ID assigned to this item; typically displayed using printf("%08X", id)
-`uint8_t level` | item level
-`uint8_t rarity` | see the d2rarity enum
-`bool multiplePictures` | 
-`uint8_t pictureID` | 
-`bool classSpecific` | 
-`uint16_t automagicID` | only set if classSpecific is true. automagicID = the row in automagic.txt, where the first non-header row is ID 0, and no rows are skipped when incrementing ID
-`uint8_t lowQualityID` | see d2lowquality enum
-`uint8_t superiorID` | related in some way to qualityitems.txt, unsure what the ID <-> row mapping is
-`uint16_t magicPrefix` | magicPrefix = the row in MagicPrefix.txt, where the first non-header row is ID 1, and only the "Expansion" row is skipped when incrementing ID (ID 0 is no prefix)
-`uint16_t magicSuffix` | magicSuffix = the row in MagicSuffix.txt, where the first non-header row is ID 1, and only the "Expansion" row is skipped when incrementing ID (ID 0 is no suffix)
-`uint16_t setID` | setID = the row in SetItems.txt, where the first non-header row is ID 0, and only the "Expansion" row is skipped when incrementing ID
-`uint16_t uniqueID` | uniqueID = the row in UniqueItems.txt, where the first non-header row is ID 0, and only the "Expansion" row is skipped when incrementing ID
-`uint8_t nameID1` | rare or crafted prefix, where nameID1 = the row in RarePrefix.txt, where the first non-header row is (the max ID in RareSuffix.txt)+1, and no rows are skipped when incrementing ID. For example, with the default txt files: RareSuffix.txt's max ID is 155 ('flange'), therefore, the first non-header row in RarePrefix.txt ('Beast') would be ID 156
-`uint8_t nameID2` | nameID2 = the row in RareSuffix.txt, where the first non-header row is ID 1, and no rows are skipped when incrementing ID (ID 0 is no suffix)
-`uint16_t rarePrefixes[]` | list of magic prefixes used by this rare/crafted item (see magicPrefix)
-`uint8_t numRarePrefixes` | number of valid elements in the rarePrefixes array
-`uint16_t rareSuffixes[]` | list of magic suffixes used by this rare/crafted item (see magicSuffix)
-`uint8_t numRareSuffixes` | number of valid elements in the rareSuffixes array
-`char personalizedName[]` | null-terminated name, not including the 's suffix added by the game
-`bool timestamp` | 
-`uint16_t defenseRating` | the armor value; only set if the item code is in Armor.txt
-`uint8_t maxDurability` | only set if the item code has durability (i.e. is in Armor.txt or Weapons.txt) but can be 0 for items that don't have durability (i.e. phase blade)
-`uint8_t currentDurability` | only set if maxDurability > 0
-`uint16_t quantity` | only set for stackable items (i.e. the stackable column in its .txt is 1)
-`uint8_t numSockets` | number of total sockets in the item (regardless of their filled state)
-`d2itemproplist magicProperties` | list of magic properties, not including set bonuses, runeword properties, or the properties of any socketed items
-`d2itemproplist setBonuses[]` | list of currently active set bonuses (i.e. this is only non-empty when multiple set pieces are worn at the same time)
-`uint8_t numSetBonuses` | number of valid elements in the setBonuses array
-`d2itemproplist runewordProperties` | list of magic properties added to the item via a runeword (see also `isRuneword`)
-
-##### `d2ear`
-
-Field | Description
---- | ---
-`uint8_t classID` | class of the player
-`uint8_t level` | level of the player
-`char name[]` | null-terminated player name
-
 ## Acknowledgements
 
 - [nokka/d2s](https://github.com/nokka/d2s) - much of the d2s parsing of d2itemreader is ported from `nokka/d2s`

docs/.bookignore

@@ -0,0 +1,4 @@
+Doxyfile
+.bookignore
+make.bat
+make.sh

docs/.gitignore

@@ -0,0 +1,5 @@
+_book/
+node_modules/
+html/
+xml/
+latex/

docs/Doxyfile

@@ -0,0 +1,50 @@
+# Doxyfile 1.8.11
+
+PROJECT_NAME           = "d2itemreader"
+OUTPUT_DIRECTORY       =
+OPTIMIZE_OUTPUT_FOR_C  = YES
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+INLINE_SIMPLE_STRUCTS  = YES
+TYPEDEF_HIDES_STRUCT   = YES
+EXTRACT_ALL            = YES
+EXTRACT_STATIC         = NO
+
+# The INPUT tag is used to specify the files and/or directories that contain
+# documented source files. You may enter file names like myfile.cpp or
+# directories like /usr/src/myproject. Separate the files or directories with
+# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
+# Note: If this tag is empty the current directory is searched.
+
+INPUT                  = ../src/d2itemreader.h
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+CLASS_DIAGRAMS         = NO
+
+#---------------------------------------------------------------------------
+# Configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that
+# captures the structure of the code including all documentation.
+# The default value is: NO.
+
+GENERATE_XML           = YES
+
+# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
+# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
+# it.
+# The default directory is: xml.
+# This tag requires that the tag GENERATE_XML is set to YES.
+
+XML_OUTPUT             = xml
+
+# If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program
+# listings (including syntax highlighting and cross-referencing information) to
+# the XML output. Note that enabling this will significantly increase the size
+# of the XML output.
+# The default value is: YES.
+# This tag requires that the tag GENERATE_XML is set to YES.
+
+XML_PROGRAMLISTING     = YES

docs/SUMMARY.md

@@ -0,0 +1,4 @@
+# Summary
+
+* [Introduction](INDEX.md)
+* [API Reference](api.md)

docs/_layouts/website/page.html

@@ -0,0 +1,98 @@
+{% extends "website/layout.html" %}
+
+{% block title %}{{ page.title }} · {{ super() }}{% endblock %}
+{% block description %}{{ page.description }}{% endblock %}
+
+{% block head %}
+    {{ super() }}
+
+    {% if page.next and page.next.path %}
+    <link rel="next" href="{{ page.next.path|resolveFile }}" />
+    {% endif %}
+    {% if page.previous and page.previous.path %}
+    <link rel="prev" href="{{ page.previous.path|resolveFile }}" />
+    {% endif %}
+{% endblock %}
+
+{% block body %}
+<div class="gb-page-wrapper">
+    <header class="gb-page-header">
+        <div class="container">
+        {% block header %}
+            {% block search_input %}{% endblock %}
+
+            <a href="{{ "/"|resolveFile }}" class="logo">
+                <h1>{{ config.title }}</h1>
+            </a>
+
+            <a href="{{ config.github_url }}" class="btn btn-link pull-right hidden-xs"><i class="octicon octicon-mark-github"></i> Github</a>
+
+            {% if glossary.length > 0 %}
+            <a href="{{ ('/' + glossary.path)|resolveFile }}" class="btn btn-link pull-right hidden-xs">Glossary</a>
+            {% endif %}
+
+            {% block header_nav %}
+                {% if page.next and page.next.path %}
+                <a href="{{ page.next.path|resolveFile }}" class="btn btn-link pull-right hidden-xs">
+                    <i class="octicon octicon-chevron-right"></i>
+                </a>
+                {% endif %}
+                {% if page.previous and page.previous.path %}
+                <a href="{{ page.previous.path|resolveFile }}" class="btn btn-link pull-right hidden-xs">
+                    <i class="octicon octicon-chevron-left"></i>
+                </a>
+                {% endif %}
+            {% endblock %}
+        {% endblock %}
+        </div>
+    </header>
+
+    <div class="gb-page-body">
+        <div class="gb-page-inner">
+            <div class="container">
+                <div class="row">
+                    <div class="col-md-3">
+                        {% include "website/sidenav.html" %}
+                    </div>
+                    <div class="col-md-9">
+                        {% block search_results %}
+                            {% block page %}
+                            <div class="gb-markdown book-page-inner">
+                                {{ page.content|safe }}
+                            </div>
+                            {% endblock %}
+                        {% endblock %}
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <footer class="gb-page-footer">
+        <div class="container">
+            <ul class="menu">
+                <li>
+                    <a href="#">Return to the top</a>
+                </li>
+                <li>
+                    <a href="#">Updated {{ file.mtime|date('MMM Do YY') }}</a>
+                </li>
+            </ul>
+        </div>
+    </footer>
+</div>
+
+<script src="{{ "gitbook.js"|resolveAsset }}"></script>
+{% for resource in plugins.resources.js %}
+    {% if resource.url %}
+    <script src="{{ resource.url }}"></script>
+    {% else %}
+    <script src="{{ resource.path|resolveAsset }}"></script>
+    {% endif %}
+{% endfor %}
+<script>
+(function() {
+    gitbook.page.hasChanged({{ template.getJSContext()|dump|safe }});
+})();
+</script>
+{% endblock %}

docs/book.json

@@ -0,0 +1,8 @@
+{
+	"plugins": ["theme-official","-sharing","-fontsettings","-search"],
+	"title": "d2itemreader",
+	"github_url": "https://github.com/squeek502/d2itemreader",
+	"structure": {
+		"readme": "INDEX.md"
+	}
+}

docs/make.bat

@@ -0,0 +1,9 @@
+@echo off
+
+call npm install https://github.com/squeek502/moxygen
+
+call doxygen
+copy /Y "../README.md" "./INDEX.md"
+call "./node_modules/.bin/moxygen" ./xml --anchors
+call gitbook install
+call gitbook build

docs/make.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+npm install https://github.com/squeek502/moxygen
+
+doxygen
+cp -f "../README.md" "./INDEX.md"
+"./node_modules/.bin/moxygen" ./xml --anchors
+gitbook install
+gitbook build

docs/styles/website.css

@@ -0,0 +1,9 @@
+.gb-markdown h3 {
+  padding-top: 1.5rem;
+  border-top: 1px solid #ddd;
+  box-shadow: 0 -2px 5px 0 rgba(140, 144, 155, 0.15);
+}
+
+.gb-markdown h4 {
+  font-size: 1em;
+}