From 8e26f21d622d778d5d61b891955277e8740c8e67 Mon Sep 17 00:00:00 2001 From: John Bytheway Date: Mon, 10 Feb 2020 22:59:44 -0500 Subject: [PATCH 1/6] Mention cddatags in the JSON docs --- doc/JSON_INFO.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/JSON_INFO.md b/doc/JSON_INFO.md index 558aefa103f23..ed9b4d0efdb00 100644 --- a/doc/JSON_INFO.md +++ b/doc/JSON_INFO.md @@ -3,6 +3,7 @@ Use the `Home` key to return to the top. - [Introduction](#introduction) +- [Navigating the JSON](#navigating-the-json) - [File descriptions](#file-descriptions) * [`data/json/`](#datajson) * [`data/json/items/`](#datajsonitems) @@ -162,6 +163,11 @@ Use the `Home` key to return to the top. # Introduction This document describes the contents of the json files used in Cataclysm: Dark days ahead. You are probably reading this if you want to add or change content of Catacysm: Dark days ahead and need to learn more about what to find where and what each file and property does. +# Navigating the JSON +A lot of the JSON involves cross-references to other JSON entities. To make it easier to navigate, we provide a script `tools/json_tools/cddatags.py` that can build a `tags` file for you. If your editor has [ctags support](http://ctags.sourceforge.net/) then you can use this file to easily jump to the definition of any entity. For example, in Vim you can jump by positioning your cursor over an id and hitting `^]` (by default). + +`cddatags.py` is designed to safely update a tags file containing source code tags, so if you want both types of tag in your `tags` file then you can run `ctags -R . && tools/json_tools/cddatags.py`. + # File descriptions Here's a quick summary of what each of the JSON files contain, broken down by folder. This list is not comprehensive, but covers the broad strokes. From 0e0b84d02f7daa06614c6746c942b667aedbdf7d Mon Sep 17 00:00:00 2001 From: John Bytheway Date: Mon, 10 Feb 2020 23:13:08 -0500 Subject: [PATCH 2/6] Strip platform-specific path separator for tags This is fixing a hypothetical bug which I think cddatags would have suffered from on Windows (but untested there). --- tools/json_tools/cddatags.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/json_tools/cddatags.py b/tools/json_tools/cddatags.py index 15b13bbcc0d74..369b301850cc7 100755 --- a/tools/json_tools/cddatags.py +++ b/tools/json_tools/cddatags.py @@ -35,7 +35,7 @@ def main(args): if filename.endswith('.json'): full_path = os.path.join(dirpath, filename) assert full_path.startswith(TOP_DIR) - relative_path = full_path[len(TOP_DIR):].lstrip('/') + relative_path = full_path[len(TOP_DIR):].lstrip(os.path.sep) with open(full_path) as file: try: json_data = json.load(file) From 2e9c21bd2b5916904290c60057dd998d1e6e9d94 Mon Sep 17 00:00:00 2001 From: John Bytheway Date: Tue, 11 Feb 2020 21:41:47 -0500 Subject: [PATCH 3/6] Use cddatags in Makefile There were already two rules for creating tags; update them both. --- Makefile | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 48c4ab9679225..91a67a3bfdb47 100644 --- a/Makefile +++ b/Makefile @@ -1039,12 +1039,13 @@ endif export ODIR _OBJS LDFLAGS CXX W32FLAGS DEFINES CXXFLAGS TARGETSYSTEM -ctags: $(SOURCES) $(HEADERS) $(TESTSRC) $(TESTHDR) - ctags $(SOURCES) $(HEADERS) $(TESTSRC) $(TESTHDR) +ctags: $(ASTYLE_SOURCES) + ctags $^ + ./tools/json_tools/cddatags.py -etags: $(SOURCES) $(HEADERS) $(TESTSRC) $(TESTHDR) - etags $(SOURCES) $(HEADERS) $(TESTSRC) $(TESTHDR) - find data -name "*.json" -print0 | xargs -0 -L 50 etags --append +etags: $(ASTYLE_SOURCES) + etags $^ + ./tools/json_tools/cddatags.py astyle: $(ASTYLE_SOURCES) $(ASTYLE_BINARY) --options=.astylerc -n $(ASTYLE_SOURCES) From 9497aa79ebecb5288348de0dc6d7ca3f286e4c6c Mon Sep 17 00:00:00 2001 From: John Bytheway Date: Wed, 12 Feb 2020 07:36:17 -0500 Subject: [PATCH 4/6] Move some cddatags docs to DEVELOPER_TOOLING The second paragraph was not useful to non-code-writing contributors, so move it and rewrite it. --- doc/DEVELOPER_TOOLING.md | 5 +++++ doc/JSON_INFO.md | 2 -- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/DEVELOPER_TOOLING.md b/doc/DEVELOPER_TOOLING.md index 439fe3442c919..d87545d13a49e 100644 --- a/doc/DEVELOPER_TOOLING.md +++ b/doc/DEVELOPER_TOOLING.md @@ -42,6 +42,11 @@ On Windows, there is an [AStyle extension for Visual Studio](https://github.com/ See the [JSON style guide](JSON_STYLE.md). +## ctags + +In addition to the usual means of creating a `tags` file via e.g. [`ctags`](http://ctags.sourceforge.net/), we provide `tools/json_tools/cddatags.py` to augment a `tags` file with locations of definitions taken from CDDA JSON data. `cddatags.py` is designed to safely update a tags file containing source code tags, so if you want both types of tag in your `tags` file then you can run `ctags -R . && tools/json_tools/cddatags.py`. Alternatively, there is a rule in the `Makefile` to do this for you; just run `make ctags` or `make etags`. + + ## clang-tidy Cataclysm has a [clang-tidy configuration file](../.clang-tidy) and if you have diff --git a/doc/JSON_INFO.md b/doc/JSON_INFO.md index ed9b4d0efdb00..d88527cc88c0b 100644 --- a/doc/JSON_INFO.md +++ b/doc/JSON_INFO.md @@ -166,8 +166,6 @@ This document describes the contents of the json files used in Cataclysm: Dark d # Navigating the JSON A lot of the JSON involves cross-references to other JSON entities. To make it easier to navigate, we provide a script `tools/json_tools/cddatags.py` that can build a `tags` file for you. If your editor has [ctags support](http://ctags.sourceforge.net/) then you can use this file to easily jump to the definition of any entity. For example, in Vim you can jump by positioning your cursor over an id and hitting `^]` (by default). -`cddatags.py` is designed to safely update a tags file containing source code tags, so if you want both types of tag in your `tags` file then you can run `ctags -R . && tools/json_tools/cddatags.py`. - # File descriptions Here's a quick summary of what each of the JSON files contain, broken down by folder. This list is not comprehensive, but covers the broad strokes. From d25254b0ad9cd7fa7e6872b0b9250b57e90d15d8 Mon Sep 17 00:00:00 2001 From: John Bytheway Date: Wed, 12 Feb 2020 19:36:23 -0500 Subject: [PATCH 5/6] cddatags: Force UTF-8 encoding for json files --- tools/json_tools/cddatags.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/json_tools/cddatags.py b/tools/json_tools/cddatags.py index 369b301850cc7..06b57d1ff845a 100755 --- a/tools/json_tools/cddatags.py +++ b/tools/json_tools/cddatags.py @@ -36,7 +36,7 @@ def main(args): full_path = os.path.join(dirpath, filename) assert full_path.startswith(TOP_DIR) relative_path = full_path[len(TOP_DIR):].lstrip(os.path.sep) - with open(full_path) as file: + with open(full_path, encoding='utf-8') as file: try: json_data = json.load(file) except Exception as err: From af947fce921fd17550c4d7106bb1aaead279974b Mon Sep 17 00:00:00 2001 From: John Bytheway Date: Wed, 12 Feb 2020 19:51:25 -0500 Subject: [PATCH 6/6] Expand on the cddatags docs Thanks to snipercup for researching useful tips for Windows. --- doc/JSON_INFO.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/JSON_INFO.md b/doc/JSON_INFO.md index d88527cc88c0b..d6dd7a3ce2882 100644 --- a/doc/JSON_INFO.md +++ b/doc/JSON_INFO.md @@ -164,7 +164,14 @@ Use the `Home` key to return to the top. This document describes the contents of the json files used in Cataclysm: Dark days ahead. You are probably reading this if you want to add or change content of Catacysm: Dark days ahead and need to learn more about what to find where and what each file and property does. # Navigating the JSON -A lot of the JSON involves cross-references to other JSON entities. To make it easier to navigate, we provide a script `tools/json_tools/cddatags.py` that can build a `tags` file for you. If your editor has [ctags support](http://ctags.sourceforge.net/) then you can use this file to easily jump to the definition of any entity. For example, in Vim you can jump by positioning your cursor over an id and hitting `^]` (by default). +A lot of the JSON involves cross-references to other JSON entities. To make it easier to navigate, we provide a script `tools/json_tools/cddatags.py` that can build a `tags` file for you. + +To run the script you'll need Python 3. On Windows you'll probably need to install that, and associate `.py` files with Python. Then open a command prompt, navigate to your CDDA folder, and run `tools\json_tools\cddatags.py`. + +To use this feature your editor will need [ctags support](http://ctags.sourceforge.net/). When that's working you should be able to easily jump to the definition of any entity. For example, by positioning your cursor over an id and hitting the appropriate key combination. + +* In Vim, this feature exists by default, and you can jump to a definition using [`^]`](http://vimdoc.sourceforge.net/htmldoc/tagsrch.html#tagsrch.txt). +* In Notepad++ go to "Plugins" -> "Plugins Admin" and enable the "TagLEET" plugin. Then select any id and press Alt+Space to open the references window. # File descriptions Here's a quick summary of what each of the JSON files contain, broken down by folder. This list is not comprehensive, but covers the broad strokes.