I have installed Sphinx in order to document some Python modules and class I'm working on. While the markup language looks very nice, I haven't managed to auto-document a Python code.
Basically, I have the following Python module:
SegLib.py
And A class called Seg in it. I would like to display the docstrings of the class and module within the generated Sphinx document, and add further formatted text to it.
My index.rst looks like this:
Contents:
.. toctree::
:maxdepth: 2
chapter1.rst
and chapter1.rst:
This is a header
================
Some text, *italic text*, **bold text**
* bulleted list. There needs to be a space right after the "*"
* item 2
.. note::
This is a note.
See :class:`Seg`
But Seg is just printed in bold, and not linked to an auto-generated documentation of the class.
Trying the following didn't help, either:
See :class:`Seg`
Module :mod:'SegLib'
Module :mod:'SegLib.py'
Edit: changed SegLib to segments (thanks, iElectric!), and changed chapter1.rst to:
The :mod:`segments` Module
--------------------------
.. automodule:: segments.segments
.. autoclass:: segments.segments.Seg
Still, can't get Sphinx to directly document functions within a class, or better - to automatically add all the functions within a class to the document. Tried:
.. autofunction:: segments.segments.Seg.sid
and got:
autodoc can't import/find function 'segments.segments.Seg.sid', it reported error: "No module named Seg"
Any ideas how to auto-document the functions and classes with a short command?
Add to the beginning of the file:
.. module:: SegLib
Try using :autoclass: directive for class doc.
BTW: module names should be lower_case.
EDIT: I learned a lot from reading other source files.
Related
I am building code documentation with Sphinx.
Let's say at some point there is documentation for a class foobar.Foo, i.e. something like
.. autoclass:: foobar.Foo
:members:
At some other place, I have a code example (included using literalinclude), which contains the line
foo = foobar.Foo()
Is there a way to make the foobar.Foo in the code example automatically link to the documentation of that class like when using
:class:`foobar.Foo`
in normal text?
I wrote a little tutorial in rst format. Now for the documentation generated by apidoc, I would like to reference that tutorial in the docstring using:
:any:`<my_tut>`
Where my_tut.rst is in the top level directory of my Sphinx-documentation source-folder. However, I get the error
WARNING: 'any' reference target not found: my_tut
Added info:
The output of apidoc is not in the toplevel source folder, but in a subfolder called code.
The :doc: role can be used to create a cross-reference to my_tut.rst:
:doc:`my_tut`
If the link source and the link target are in different folders, that needs to be taken into account. With a target one level above the source, it would look like this:
:doc:`../my_tut`
An alternative is to add a label immediately before the relevant heading in my_tut.rst and use that as the cross-reference target. If the label definition is .. _my_label:, you would reference it like this:
:any:`my_label`
You could also use :ref:`my_label`.
I have some javascript code which uses d3 sankey plugin for creating a chart. In my new project, I need to reuse the same code, but the new project is in typescript. I am looking for a DefinitelyTyped file for the plugin. I browsed through https://github.com/DefinitelyTyped/DefinitelyTyped, but couldn't find it.
Is there any other location where I can get this file from?
Sankey plugin link: https://github.com/d3/d3-sankey
Also, without a d.ts file for this plugin, is there a way to access it through typescript?
The code in d3 plugin looks something like this:
d3.sankey = function () {
// Rest of the code goes here
}
The way I use it in javascript is as below:
d3.sankey().nodeWidth(30).size([100,100]);
Would appreciate any help or guidance.
Thanks!
As a heads-up, I have just submitted a Pull Request #16051 to DefinitelyTyped which contains TS definitions for d3-sankey.
Once they are merged, they will be published as per standard process to npm/#types. I.e. npm install --save-dev #types/d3-sankey will do.
IMPORTANT: When I wrote them up, I noticed that the current API documentation in the d3-sankey repo appears to be in some need of rectification (e.g. missing methods, mentioning of accessor functions, which are not used in the code base)
When I have a second, I will file an issue there/submit a PR.
UPDATE (2017-05-01):
The "official" TypeScript definitions for d3-sankey are now available (see npm #types/d3-sankey). Simply use them with npm as indicated above.
The PR to update the actual API documentation of d3-sankey to reflect the source code is still awaiting a merge here.
You need to expand the definition of the d3 type to include the sankey() method and the methods it accepts.
At the absolute minimum, you need to extend the d3 module with a declaration file to make clear that d3 has been extended with the d3-sankey module. You do so by creating a definition file that you place within the #types directly with the following contents:
declare module 'd3' {
export function sankey(...args[]) : any;
}
This tells TS that there is a d3 module, and that it exports the function listed. If the d3 module already exists, it extends that module.
So you can then import the d3 service and use it:
import dd3 = require('d3');
dd3.sankey();
If you want to expand on the type file, you instead write the definition file as so:
declare module 'd3' {
interface ISankey {
nodeWidth() : number;
nodeWidth(width : number|{(arg: number) : number}) : void;
// Add Other d3.sankey Methods Here
}
export function sankey() : ISankey;
}
I have a gem which uses Faker to help build mock data. I'd like to add a new class that generates a new category of stuff, using the same syntax Faker itself uses. The first half is easy, I simply define the class, and make sure my gem loads the file:
# lib/faker/restaurant.rb
module Faker
class Restaurant < Base
class << self
def name
parse('restaurant.name')
end
end
end
end
So far, so good. Now, to describe what values can come out of this, I create a YAML file:
faker:
en:
restaurant:
suffix: [Cafe,Restaurant]
name:
- "#{Name.first_name}'s #{suffix}"
So, the actual question: Where does this file go, and what name should it have? If this were a Rails application, it would be config/locales/faker.en.yml. In a gem, that doesn't appear to work - there isn't actually a 'config' directory, for one thing, but creating it for this purpose doesn't help, I get:
> Faker::Restaurant.name
I18n::MissingTranslationData: translation missing: en.faker.restaurant.name
Ok, figured it out. Special thanks to dax, whose comments prodded me in the right direction.
Faker uses the I18n gem for localization (which is why the YAML files live in a 'locales' directory). This means that I needed to add my custom YAML to the I18n load path. It doesn't matter exactly where the files are, as long as they're added to the load path. In my case, I put it at lib/faker/locales/en-US.yml, and added that entire directory to the load path, thus:
lib/my_gem.rb:
I18n.load_path += Dir[File.join(File.expand_path(File.dirname(__FILE__)), 'faker/locales', '*.yml')]
require "faker/restaurant"
Any .yml files I put in that directory should be loaded and available to Faker.
Side note: I also needed to change the YAML format slightly - it should be
en:
faker:
<stuff>
rather than with faker at the top level, as I had it.
Liquid has two filters named newline_to_br and escape.
I'm working on a Jekyll plugin that needs to run a string through those filters. Rather than install a separate gem which does this, or write my own code for it, is there any way to call those filters directly from inside of the plugin?
Those filters can become available with the line include Liquid::StandardFilters.
For example:
class PlaintextConverter
include Liquid::StandardFilters
def convert(content)
content = escape(content)
content = newline_to_br(content)
content
end
end
For a full list of functions that become available in this way, you can view the source of standardfilters.rb