From f78ff95bc5de863c5bd2420e4cc1a7eb05f06319 Mon Sep 17 00:00:00 2001 From: John Bytheway Date: Sat, 15 Feb 2020 07:58:22 +0000 Subject: [PATCH] Improve discoverability of cddatags (#37954) * Mention cddatags in the JSON docs * 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). * Use cddatags in Makefile There were already two rules for creating tags; update them both. * Move some cddatags docs to DEVELOPER_TOOLING The second paragraph was not useful to non-code-writing contributors, so move it and rewrite it. * cddatags: Force UTF-8 encoding for json files * Expand on the cddatags docs Thanks to snipercup for researching useful tips for Windows. --- Makefile | 11 ++++++----- doc/DEVELOPER_TOOLING.md | 5 +++++ doc/JSON_INFO.md | 11 +++++++++++ tools/json_tools/cddatags.py | 4 ++-- 4 files changed, 24 insertions(+), 7 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) 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 3443dd76c5bc0..bfb54f0326c44 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,16 @@ 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. + +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. diff --git a/tools/json_tools/cddatags.py b/tools/json_tools/cddatags.py index 15b13bbcc0d74..06b57d1ff845a 100755 --- a/tools/json_tools/cddatags.py +++ b/tools/json_tools/cddatags.py @@ -35,8 +35,8 @@ 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('/') - with open(full_path) as file: + relative_path = full_path[len(TOP_DIR):].lstrip(os.path.sep) + with open(full_path, encoding='utf-8') as file: try: json_data = json.load(file) except Exception as err: