I can successfully generated Puppet documentation for my modules' classes (using puppet-doc) but I would also like to include a module-level documentation (similar to http://docs.puppetlabs.com/puppet/3/reference/modules_documentation.html.) I tried to put a README.md, README.markdown, [modulename].md or [modulename].markdown at the module top-level but without success.
What is the line I missed to read on the documentation?
Documentation at PuppetLabs suggests that README is respected, not README.md or .markdown.
Seeing as puppet doc is basically rdoc, it doesn't support typical markdown and instead expects an rdoc format, or just plain text.
Related
Really sorry if this has been answered somewhere… Does anyone know if a #types/ npm library exists for ExcelScript? Or even an ExcelScript.d.ts file somewhere?
Sumurthy on GitHub wrote a file, index.d.ts, to do this. You can take a look at that file here.
The type definitions for Office Scripts are not open source. A copy of those definitions is used to generate the reference documentation. It is updated shortly after the internal definitions are updated. You can find a public copy of the .d.ts file here: https://github.com/OfficeDev/office-scripts-docs-reference/blob/main/generate-docs/script-inputs/excel.d.ts
I am trying to customize the color of the LaTeX inline formula when using Sphinx documentation package, and html output.
The details:
I have a file called func.rst, which includes the following line:
Let :math:`x_{1}` be a binary variable.
which is rendered successfully into LaTeX in the documentation I created with Sphinx.
(I have 'sphinx.ext.imgmath' listed in extensions in conf.py)
My goal is to have x_{1} colored in red.
Things I tried:
Adding the color inside the formula:
Let :math:`\color{red}x_{1}` be a binary variable.
while also defining
latex_elements['preamble'] = '\usepackage{xcolor}'
in the conf.py file.
Trying to define all math output globally with:
latex_elements['preamble'] = r'''
\usepackage{xcolor}
\everymath{\color{red}}
\everydisplay{\color{red}}
'''
Needless to say, both (and many more less promising ideas) failed.
Copying over my answer on cross-posted question at tex.sx:
As you seem to be targeting html with math rendered as PNGs images (or SVGs), the current config value to configure isn't latex_elements, but imgmath_latex_preamble.
I tested since and it works.
For completeness sake, I am adding here the full solution. (THANKS jfbu!)
In conf.py I defined extensions = ['sphinx.ext.imgmath', <some_more_unrelated_stuff>]
Also in conf.py I defined
imgmath_latex_preamble=r'\usepackage{xcolor}'
(EDIT: in ooposed to what I previously wrote,there is no need to define in addition imgmath_latex="/usr/local/texlive/2017/bin/x86_64-darwin/latex" thanks jfbu again)
In the .rst file where I have the latex expression, I have
Let :math:`\color{red}x_{1}` be a binary variable.
In the terminal I run
make clean html
("make clean" is the sphinx's best friend)
And its working! wohoo!
I was wondering whether Node.js/npm include any kind of exension mechanism comparable to Python setuptools' "entry points".
So, in short:
is there any way I can do dynamic discovery of services provided by other packages using npm?
if not, what would be the best way to implement something similar? Specifying the extension name in the main module's configuration file seems to be the logical solution, but I wonder whether something "automatic" can be done.
I'm not aware of any builtin mechanism to do this.
One viable way of doing it yourself:
I made a small tool (Jumpstart) to quickly create project scaffolding from templates with placeholders, and I used a kind of plugin mechanism for that. It basically comes down to that the Jumpstart script searches for modules named jumpstart-* "adjacent" to where the module itself is installed. So it would work for both local and global installations. If installed locally, it would search the other local modules (on the same level) and if global, it searches the other global modules.
Note that here, "search" comes down to a simple fs.exists check to see if there's a Jumpstart template module with a particular name installed. However, nothing would stand in the way to actually get a full list of all installed packages matching the jumpstart-* pattern, and loading all at once. I could also search up the entire directory tree for node_modules directories and do the same. There's no point in doing this for this particular program, however.
See https://npmjs.org/package/jumpstart for docs.
The only limitation to this technique is that all modules must be named in a consistent fashion. Start with some string, end with some string, something like that. Any rogue packages polluting the namespace could be detected by doing further checks on a package contents: What files does it contain? What kind of object does its main module export? etc.
Brunch also uses a plugin mechanism. This one actually deals with file extensions, so is more relevant: https://github.com/brunch/brunch/wiki/Plugins . See for example source of the CoffeeScript plugin https://github.com/brunch/coffee-script-brunch/blob/master/src/index.coffee .
The ~/.cabal/config stores configuration which cabal-install uses. I wanted to do some hackery on it. (Specifically, having multiple GHC versions installed, I wish to have separate documentation indexes).
I couldn't, however, find any documentation about its' syntax or variables except for what is included in default file. Is there any documentation available?
Edit: I've stated the goal above, but let me add some details: If the same package (eg. GTK) is installed in two versions of GHC they end up in the same documentation index file. I wan't that local documentation index to be separate for each GHC installation. I believe it is possible in some way using documentation directory setting, but there has to be a variable for currently used GHC version. If there isn't one there might be some workarounds available, but I won't be able to say that unless I see the documentation.
This seems to work, although I've only tested it with one version of GHC:
documentation: True
doc-index-file: $datadir/doc/$compiler/index.html
install-dirs user
docdir: $datadir/doc/$compiler/$pkgid
With the other options left at the default, this generates documentation in .cabal/share/doc/<ghc-version>/<package-name>, and the index in .cabal/share/doc/<ghc-version>/index.html.
There appears to be very little online - not even the haddocks for the cabal-install code. So your best bet may be to puzzle it out from the source. cabal unpack cabal-install, or view the cabal-install repo online. Look at SavedConfig in Distribution/Client/Config.hs. As an example, it imports GlobalFlags from Setup.hs; the individual flags, eg globalCacheDir, are associated with their config-file syntax (which is also the command-line syntax) in the globalCommand function below, remote-repo-cache in this case.
You should also ask dcoutts in the #haskell channel on irc.freenode.net, in case he has new docs available.
I am the author of the operational package, which includes example code. I would like this example code to be hscolored and installed together with the API documentation, which is generated by Haddock.
I probably have to use a custom Cabal build type and create a user hook for the Haddock phase. However, I never managed to make this work. Hence, my question is:
How to include full modules as example code in Haddock?
Could you give an example of a Cabal user hook that applies hscolor to an additional source code file example.hs and joins the result with the generated Haddock documentation?
I'm a total Haskell nube and this is a shot in the dark, but couldn't you use hscolour to output the code as HTML and then do something along the lines of cabal haddock --executables --hyperlink-source to include the colorized HTML?