Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix(docs): improve docs rendering #303

Merged
merged 1 commit into from
Nov 8, 2018
Merged

fix(docs): improve docs rendering #303

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 64 additions & 2 deletions packages/jsii-calc/lib/compliance.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@ export class RuntimeTypeChecking {
arg1; arg2; arg3;
}

public methodWithDefaultedArguments(arg1: number = 2, arg2: string, arg3: Date = new Date()) {
public methodWithDefaultedArguments(arg1: number = 2, arg2?: string, arg3: Date = new Date()) {
arg1; arg2; arg3;
}

Expand All @@ -258,7 +258,7 @@ export class OptionalConstructorArgument {

export class DefaultedConstructorArgument {
public constructor(public readonly arg1: number = 2,
public readonly arg2: string,
public readonly arg2?: string,
public readonly arg3: Date = new Date()) {}
}

Expand Down Expand Up @@ -994,3 +994,65 @@ export interface NullShouldBeTreatedAsUndefinedData {
arrayWithThreeElementsAndUndefinedAsSecondArgument: any[];
}

/**
* jsii#298: show default values in sphinx documentation, and respect newlines.
**/
export interface LoadBalancedFargateServiceProps {
/**
* The number of cpu units used by the task.
* Valid values, which determines your range of valid values for the memory parameter:
* 256 (.25 vCPU) - Available memory values: 0.5GB, 1GB, 2GB
* 512 (.5 vCPU) - Available memory values: 1GB, 2GB, 3GB, 4GB
* 1024 (1 vCPU) - Available memory values: 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB
* 2048 (2 vCPU) - Available memory values: Between 4GB and 16GB in 1GB increments
* 4096 (4 vCPU) - Available memory values: Between 8GB and 30GB in 1GB increments
*
* This default is set in the underlying FargateTaskDefinition construct.
*
* @default 256
*/
cpu?: string;

/**
* The amount (in MiB) of memory used by the task.
*
* This field is required and you must use one of the following values, which determines your range of valid values
* for the cpu parameter:
*
* 0.5GB, 1GB, 2GB - Available cpu values: 256 (.25 vCPU)
*
* 1GB, 2GB, 3GB, 4GB - Available cpu values: 512 (.5 vCPU)
*
* 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB - Available cpu values: 1024 (1 vCPU)
*
* Between 4GB and 16GB in 1GB increments - Available cpu values: 2048 (2 vCPU)
*
* Between 8GB and 30GB in 1GB increments - Available cpu values: 4096 (4 vCPU)
*
* This default is set in the underlying FargateTaskDefinition construct.
*
* @default 512
*/
memoryMiB?: string;

/**
* The container port of the application load balancer attached to your Fargate service. Corresponds to container port mapping.
*
* @default 80
*/
containerPort?: number;

/**
* Determines whether the Application Load Balancer will be internet-facing
*
* @default true
*/
publicLoadBalancer?: boolean;

/**
* Determines whether your Fargate Service will be assigned a public IP address.
*
* @default false
*/
publicTasks?: boolean;
}
85 changes: 80 additions & 5 deletions packages/jsii-calc/test/assembly.jsii
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1114,6 +1114,7 @@
{
"name": "arg2",
"type": {
"optional": true,
"primitive": "string"
}
},
Expand All @@ -1138,16 +1139,17 @@
},
{
"immutable": true,
"name": "arg2",
"name": "arg3",
"type": {
"primitive": "string"
"primitive": "date"
}
},
{
"immutable": true,
"name": "arg3",
"name": "arg2",
"type": {
"primitive": "date"
"optional": true,
"primitive": "string"
}
}
]
Expand Down Expand Up @@ -1996,6 +1998,78 @@
}
]
},
"jsii-calc.LoadBalancedFargateServiceProps": {
"assembly": "jsii-calc",
"datatype": true,
"docs": {
"comment": "jsii#298: show default values in sphinx documentation, and respect newlines."
},
"fqn": "jsii-calc.LoadBalancedFargateServiceProps",
"kind": "interface",
"name": "LoadBalancedFargateServiceProps",
"properties": [
{
"abstract": true,
"docs": {
"comment": "The container port of the application load balancer attached to your Fargate service. Corresponds to container port mapping.",
"default": "80"
},
"name": "containerPort",
"type": {
"optional": true,
"primitive": "number"
}
},
{
"abstract": true,
"docs": {
"comment": "The number of cpu units used by the task.\nValid values, which determines your range of valid values for the memory parameter:\n256 (.25 vCPU) - Available memory values: 0.5GB, 1GB, 2GB\n512 (.5 vCPU) - Available memory values: 1GB, 2GB, 3GB, 4GB\n1024 (1 vCPU) - Available memory values: 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB\n2048 (2 vCPU) - Available memory values: Between 4GB and 16GB in 1GB increments\n4096 (4 vCPU) - Available memory values: Between 8GB and 30GB in 1GB increments\n\nThis default is set in the underlying FargateTaskDefinition construct.",
"default": "256"
},
"name": "cpu",
"type": {
"optional": true,
"primitive": "string"
}
},
{
"abstract": true,
"docs": {
"comment": "The amount (in MiB) of memory used by the task.\n\nThis field is required and you must use one of the following values, which determines your range of valid values\nfor the cpu parameter:\n\n0.5GB, 1GB, 2GB - Available cpu values: 256 (.25 vCPU)\n\n1GB, 2GB, 3GB, 4GB - Available cpu values: 512 (.5 vCPU)\n\n2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB - Available cpu values: 1024 (1 vCPU)\n\nBetween 4GB and 16GB in 1GB increments - Available cpu values: 2048 (2 vCPU)\n\nBetween 8GB and 30GB in 1GB increments - Available cpu values: 4096 (4 vCPU)\n\nThis default is set in the underlying FargateTaskDefinition construct.",
"default": "512"
},
"name": "memoryMiB",
"type": {
"optional": true,
"primitive": "string"
}
},
{
"abstract": true,
"docs": {
"comment": "Determines whether the Application Load Balancer will be internet-facing",
"default": "true"
},
"name": "publicLoadBalancer",
"type": {
"optional": true,
"primitive": "boolean"
}
},
{
"abstract": true,
"docs": {
"comment": "Determines whether your Fargate Service will be assigned a public IP address.",
"default": "false"
},
"name": "publicTasks",
"type": {
"optional": true,
"primitive": "boolean"
}
}
]
},
"jsii-calc.Multiply": {
"assembly": "jsii-calc",
"base": {
Expand Down Expand Up @@ -2713,6 +2787,7 @@
{
"name": "arg2",
"type": {
"optional": true,
"primitive": "string"
}
},
Expand Down Expand Up @@ -3537,5 +3612,5 @@
}
},
"version": "0.7.8",
"fingerprint": "FZk0ePQ2XUte84CmnOjU3PPCl6QUA88ke6wHIJKhyzo="
"fingerprint": "3UAOWGBZzphiNp40hKAbXcsM27uWdwmXnbiPU74ZroU="
}
29 changes: 17 additions & 12 deletions packages/jsii-pacmak/lib/targets/sphinx.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -254,12 +254,12 @@ class SphinxDocsGenerator extends Generator {
//
// Properties

protected onProperty(_cls: spec.ClassType, prop: spec.Property) {
this.renderProperty(prop);
protected onProperty(cls: spec.ClassType, prop: spec.Property) {
this.renderProperty(cls, prop);
}

protected onStaticProperty(_cls: spec.ClassType, prop: spec.Property) {
this.renderProperty(prop);
protected onStaticProperty(cls: spec.ClassType, prop: spec.Property) {
this.renderProperty(cls, prop);
}

//
Expand Down Expand Up @@ -357,8 +357,8 @@ class SphinxDocsGenerator extends Generator {
this.onInterfaceMethod(ifc, overload);
}

protected onInterfaceProperty(_ifc: spec.InterfaceType, property: spec.Property) {
this.renderProperty(property);
protected onInterfaceProperty(ifc: spec.InterfaceType, property: spec.Property) {
this.renderProperty(ifc, property);
}

private renderInheritedMembers(entity: spec.ClassType | spec.InterfaceType) {
Expand All @@ -373,7 +373,7 @@ class SphinxDocsGenerator extends Generator {
}
}
for (const property of entities.properties) {
this.renderProperty(property, source);
this.renderProperty(entity, property, source);
}
}
}
Expand Down Expand Up @@ -543,13 +543,13 @@ class SphinxDocsGenerator extends Generator {
}

private renderDocsLine(element: spec.Documentable) {
const doclines = this.renderDocs(element, false);
const doclines = this.renderDocs(element, true);
if (doclines.length === 0) {
return;
}

this.code.line();
doclines.split('\n').forEach(line => this.code.line(line));
doclines.split('\n').forEach(line => this.code.line(line + '\n'));

if (element.docs && element.docs.link) {
this.code.line(element.docs.link);
Expand Down Expand Up @@ -618,7 +618,7 @@ class SphinxDocsGenerator extends Generator {
} else {
throw new Error('Unexpected type ref');
}
if (type.optional) { result.ref = `${result.ref} or \`\`undefined\`\``; }
if (type.optional) { result.ref = `${result.ref} *(optional)*`; }
return result;

// Wrap a string between parenthesis if it contains " or "
Expand All @@ -628,7 +628,7 @@ class SphinxDocsGenerator extends Generator {
}
}

private renderProperty(prop: spec.Property, inheritedFrom?: string) {
private renderProperty(parent: spec.TypeBase, prop: spec.Property, inheritedFrom?: string) {
this.code.line();
const type = this.renderTypeRef(prop.type);
this.code.openBlock(`.. py:attribute:: ${prop.name}`);
Expand All @@ -651,9 +651,14 @@ class SphinxDocsGenerator extends Generator {
this.code.line();
}
const readonly = prop.immutable ? ' *(readonly)*' : '';
const abs = prop.abstract ? ' *(abstract)*' : '';
const abs = (parent.kind !== spec.TypeKind.Interface && prop.abstract) ? ' *(abstract)*' : '';
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder about the value of showing "abstract" at all.

Does it help consumers of a class know that a method is abstract? Or do they simply care about what it would do if they were to call it?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think they do if they are looking to extend a class.

const stat = prop.static ? ' *(static)*' : '';
this.code.line(`:type: ${type.ref}${readonly}${abs}${stat}`);

if (prop.docs && prop.docs.default) {
this.code.line(`:default: ${prop.docs.default}`);
}

this.code.closeBlock();
}

Expand Down
5 changes: 3 additions & 2 deletions packages/jsii-pacmak/test/expected.jsii-calc-base/sphinx/_scope_jsii-calc-base.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,7 @@ Base
A base class.



:abstract: Yes

.. py:method:: typeName() -> any
Expand Down Expand Up @@ -193,13 +194,13 @@ BaseProps (interface)

.. py:attribute:: bar

:type: string *(abstract)*
:type: string


.. py:attribute:: foo

*Inherited from* :py:attr:`@scope/jsii-calc-base-of-base.VeryBaseProps <@scope/jsii-calc-base-of-base.VeryBaseProps.foo>`

:type: :py:class:`@scope/jsii-calc-base-of-base.Very`\ *(abstract)*
:type: :py:class:`@scope/jsii-calc-base-of-base.Very`\


Loading