From what I understand, the --strip option of groc (a docco fork) is to allow me to strip out folders from the documentation hierarchy. eg. I have a folder structure like:
src/
module1/
coffee/
submod1/
xxx.coffee
yyy.coffee
submod2
zzz.coffee
module2/
coffee/
submod1/
xxx.coffee
yyy.coffee
submod2
zzz.coffee
I want to exclude all coffee folders from the hierarchy of the docs. How do I use strip to do that? Its not really clear in the docs
I don't think you can achieve what you're looking for with the --strip option. I believe strip only allows you to strip from the beginning of the path. I've tried "*" glob pattern matching and I couldn't get your scenario to work (eg --strip coffee and --strip */coffee)
For general usage, I use strip like this:
groc **/*.js --strip modules/WebCommon/j2ee-apps/webcommon.war/javascript
# INPUT
# modules/WebCommon/j2ee-apps/webcommon.war/javascript/validator/validator.js
# OUTPUT
# validator/validator.js
However, the filename in the actual html file still holds the entire path. That's because the template uses projectPath and not targetPath for the title.
# "projectPath":"modules/WebCommon/j2ee-apps/webcommon.war/javascript/validator/validator.js","targetPath":"validator/validator"
Admittedly, Ian MacLeod (the author) agrees that it's confusing:
https://github.com/nevir/groc/issues/13
Related
I'm trying setup a file watcher for one specific file C:\test.json via workspace.createFileSystemWatcher
This is the code I use:
const watcher = vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern("C:\\", "test.json"));
watcher.onDidChange(uri => console.log("change", uri));
watcher.onDidCreate(uri => console.log("create", uri));
watcher.onDidDelete(uri => console.log("delete", uri));
For some reason events are not triggered, unless I replace filter test.json with *.json - then it works just fine.
Any ideas why complete filename doesn't work?
I see your question(s) ;>} on github. I'll post there as well.
It is interesting that this works:
const watcher = vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.Uri.file("C:\\Testing"), "test.json"));
Note that test.json is in a folder Testing.
This does not work - when test.json is at the root of C:
const watcher = vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.Uri.file("C:\\"), "test.json"));
So it looks like either vscode.Uri.file("C:\\") doesn't work properly at the drive root level or vscode.RelativePattern() doesn't work properly at the drive root level.
As we discussed on github (see API: createFileSystemWatcher() doesn't work when filter set to a specific file), the problem appears to be the trailing slash in C:\\. Since relative patterns like new vscode.RelativePattern(vscode.Uri.file("C:\\Testing"), "test.json") work and patterns like new vscode.RelativePattern(vscode.Uri.file("C:\\Testing\\"), "test.json") do not work.
But a backslash is required for a drive root level designation:
No, it doesn't. But it's because drive path requires trailing slash,
otherwise it's treated as relative path instead:
Use a backslash as required as part of volume names, for example, the
"C:" in "C:\path\file" or the "\server\share" in
"\server\share\path\file" for Universal Naming Convention (UNC)
names.
from your comment at https://github.com/microsoft/vscode/issues/162498#issuecomment-1295628237
so it does seem that vscode.RelativePattern() will not work at the drive root level because of the trailing slash (but the trailing slash is necessary and a simple vscode.workspace.createFileSystemWatcher(vscode.Uri.file("C:\\test.json")); does not work either).
We should update this answer with however the github issue is resolved - can your original new vscode.RelativePattern(vscode.Uri.file("C:\\"), "test.json") be made to work.
I find myself in a situation where I would like to accurately document a host of custom CMake macros and functions and was wondering how to do it.
The first thing that comes to mind is simply using the built-in syntax and only document scripts, like so:
# -----------------------------
# [FUNCTION_NAME | MACRO_NAME]
# -----------------------------
# ... description ...
# -----------------------------
This is fine. However, I'd like to employ common doc generators, for instance doxygen, to also generate external documentation that can be read by anyone without looking at the implementation (which is a common scenario).
One way would be to write a simple parser that generates a corresponding C/C++ header with the appropriate signatures and documentation directly from the CMake script, which could the be processed by doxygen or comparable tools. One could also maintain such a header by hand - which is obviously tedious and error prone.
Is there any other way to employ a documentation generator with CMake scripts?
Here is the closest I could get. The following was tested with CMake 2.8.10. Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.
CMake 2.8 can extract documentation from your modules, but only documentation at the beginning of the file is considered. All documentation is added as CMake comments, beginning with a single #. Double ## will be ignored (so you can add comments to your documentation). The end of documentation is marked by the first non-comment line (e.g. an empty line)
The first line gives a brief description of the module. It must start with - and end with a period . or a blank line.
# - My first documented CMake module.
# description
or
# - My first documented CMake module
#
# description
In HTML, lines starting with at two or more spaces (after the #) are formatted with monospace font.
Example:
# - My custom macros to do foo
#
# This module provides the macro foo().
# These macros serve to demonstrate the documentation capabilietes of CMake.
#
# FOO( [FILENAME <file>]
# [APPEND]
# [VAR <variable_name>]
# )
#
# The FOO() macro can be used to do foo or bar. If FILENAME is given,
# it even writes baz.
MACRO( FOO )
...
ENDMACRO()
To generate documentation for your custom modules only, call
cmake -DCMAKE_MODULE_PATH:STRING=. --help-custom-modules test.html
Setting CMAKE_MODULE_PATH allows you to define additional directories to search for modules. Otherwise, your modules need to be in the default CMake location. --help-custom-modules limits the documentation generation to custom, non-CMake-standar modules. If you give a filename, the documentation is written to the file, to stdout otherwise. If the filename has a recognized extension, the documentation is formatted accordingly.
The following formats are possible:
.html for HTML documentation
.1 to .9 for man page
.docbook for Docbook
anything else: plain text
I am using OCLint static code analysis tool for objective-C and want to find out how to customize rules? The rules are represented by set of dylib files.
In lieu of passing configuration as arguments (see Jon Boydell's answer), you can also create a YML file named .oclint in the project directory.
Here's an example file that customizes a few things:
rules:
- LongLine
disable-rules:
rulePaths:
- /etc/rules
rule-configurations:
- key: LONG_LINE
value: 20
output: filename
report-type: xml
max-priority-1: 10
max-priority-2: 20
max-priority-3: 30
enable-clang-static-analyzer: false
The answer, as with so many things, is that it depends.
If you want to write your own custom rule then you'll need to get down and dirty into writing your own rule, in C++ on top of the existing source code. Check out the oclint-rules/rules directory, size/LongLineRule.cpp is a simple rule to get going with. You'll need to recompile, etc.
If you want to change the parameters of an existing rule you need to add the command line parameter -rc=<rulename>=<value> to the call to oclint. For example, if you want the long lines rule to only activate for lines longer than 150 chars you need to add -rc=LONG_LINE=150.
I don't have the patience to list out all the different parameters you can change. The list of rules is here http://docs.oclint.org/en/dev/rules/index.html and a list of threshold based rules here http://docs.oclint.org/en/dev/customizing/rules.html but there's no list of acceptable values and I don't know whether these two URLs cover all the rules or not. You might have to look into the source code for each rule to work out how it works.
If you're using Xcode script you should use oclint_args like this:
oclint-json-compilation-database oclint_args "-rc LONG_LINE=150" | sed
's/(..\m{1,2}:[0-9]:[0-9]*:)/\1 warning:/'
in that sample I'm changing the rule of LONG_LINE to 150 chars
I want to take a variable that has been set to a combination of path elements (potentially both absolute and relative) and get the absolute path from it. Something like what boost::filesystem::system_complete() does in C++. For example, I have something like:
set(EXTERNAL_LIB_DIR "${CMAKE_SOURCE_DIR}/../external" CACHE PATH "Location of externals")
which works but in the UI it's a bit ugly, as it might end up looking like C:/dev/repo/tool/../external. I'm wondering if there's a CMake built-in command to turn that into C:/dev/repo/external before I go and script a macro to do it. find_path kind of does this, but it requires that the path already exist and something worth searching for be there. I want it to work whether the path exists or not (I might use it for an overridden CMAKE_INSTALL_PREFIX default, for example).
You can use:
get_filename_component(NEW_VAR ${EXTERNAL_LIB_DIR} REALPATH)
As of CMake 3.20, you can use the cmake_path command to normalize the path, which supersedes the get_filename_component command.
cmake_path(SET MY_NEW_PATH NORMALIZE ${EXTERNAL_LIB_DIR})
This also converts any backslashes (\) into forward-slashes cleanly.
Seems unlikely, but is there any way to generate a set of unit tests for the following rewrite rule:
RewriteRule ^/(user|group|country)/([a-z]+)/(photos|videos)$ http:/whatever?type=$1&entity=$2&resource=$3
From this I'd like to generate a set of urls of the form:
/user/foo/photos
/user/bar/photos
/group/baz/videos
/country/bar/photos
etc...
The reason I don't want to just do this once by hand is that I'd like the bounded alternation groups (e.g. (user|group|country)) to be able to grow and maintain coverage without having the update the tests by hand.
Is there a rewrite rule or regex parser that might be able to do this, or am I doing it by hand?
If you don't mind hacking a few lines of Perl then there's a package, Regexp::Genex that you can use to generate something close to what you require e.g.
# perl -MRegexp::Genex=:all -le 'print for strings(qr/\/(user|group|country)\/([a-z]+)\//)'
/user/dxb/
/user/dx/
/user/d/
/group/xd/
/group/x/
# perl -MRegexp::Genex=:all -le 'my $re=qr/\/(user|group|country)\/([a-z]+)\/(phone|videos)/;$Regexp::Genex::DEFAULT_LEN = length $re;print for strings($re)'
/user/mgcgmccdmgdmmzccgmczgmzzdcmmd/phone
/user/mgcgmccdmgdmmzccgmczgmzzdcmm/phone
/user/mgcgmccdmgdmmzccgmczgmzzdcm/phone
/user/mgcgmccdmgdmmzccgmczgmzzdc/phone
...
/group/gg/videos
/group/g/phone
/group/g/videos
/country/jvmmm/phone
/country/jvmmm/videos
/country/jvmm/phone
/country/jvmm/videos
/country/jvm/phone
/country/jvm/videos
/country/jv/phone
/country/jv/videos
/country/j/phone
/country/j/videos
#
Note:
1) You'll need to write a wrapper to parse the source file, tokenise (extract) the source patterns, escape certain characters in the rule e.g. "/", and possibly split your rules into more manageable parts, before expanding, via Genex, and then outputting the results, in the desired format.
2) To install the module type: cpan Regexp::Genex