[Doc Rework] Devel files #1371

mapedraza · 2023-05-19T11:33:20Z

Create devel folder
Move to devel folder NorthboundInteractions.postman_collection, architecture.md, contribution.md and northboundinteractions.md
Merge development.md, usermanual.md and howto.md into devel/development.md (removing previous files)
remove doc/config-basic-example.js
rename contribution.md to contribution-guidelines.md

This PR is part of a bigger series #1329

Note: #1369 need to be merged before

fgalan · 2023-09-06T12:20:11Z

Some files has been merged/renamed. It would be great to check occurrences of the old names in repo files, in order to fix existing links, references, etc.

fgalan · 2023-09-06T12:30:49Z

doc/admin.md

Actual content changes in the text or just formatting in this file?

Probably autolinter, just formating

fgalan · 2023-09-06T12:31:11Z

doc/api.md

Actual content changes in the text or just formatting in this file?

Probably autolinter, just formating

fgalan · 2023-09-06T12:31:51Z

doc/devel/architecture.md

Actual content changes in the text or just typo fixing?

Typo + linter

fgalan · 2023-09-06T12:38:15Z

doc/devel/development.md

+
+-   _newIoTAInfo_: Object containing all the IoTA Information.
+
+## DB Models (from API document)


Are they aligned with last version of api.md?

In my opinion, tables should be simplified to avoid duplication. The Description field is already provided in api.md. Ideally, only two columns: payload and DB field, so clearly show the mapping between them (plus a "Notes" column to be used is some additional note about the mapping is worth to be said).

Done in aef1589

Added warning note here: 9390511 and noted here: #1329 (comment)

NTC

doc/devel/development.md

fgalan · 2023-09-06T12:42:13Z

doc/devel/development.md

@@ -0,0 +1,1932 @@
+# Development documentation
+


As far as I understand, this file is a merge of several things:

old development.md document

old howto.md document

old usernmanual.md document

new generated content (not sure...)

For reviewing, if would be great if we could tell the mapping between the sections in the ToC and the 4 categories above.

This is where the content comes from:

Preface

doc/development.md

Contributing

Project management

Installing dependencies

Project build

Testing

Test requirements

Debug Test

Continuous testing

Code Coverage

Clean

Checking code style

Source code style validation - ESLint

Documentation Markdown validation

Documentation Spell-checking

Prettify Code

doc/usermanual.md

Library functions and modules

Stats Registry

Alarm module

Transactions

Library overview

Function reference

Generic middlewares

doc/development.md

DB Models from API document

Service group model

Device model

Data mapping plugins

Plugins usage

Provided plugins

doc/howto.md

Developing a new IoT Agent

Protocol

Requirements

Basic IOTA

IOTA With Active attributes

IOTA With Lazy attributes

Previous considerations

Implementation

IoT Agent in multi-thread mode

Configuration management

Provisioning handlers

"Preface" is not coming from any existing document? Or it has been written from scratch?

You are right, Preface is brand new section

It comes from

iotagent-node-lib/doc/howto.md

Line 59 in d90c0d7

"dependencies": {

doc/devel/development.md

fgalan · 2023-09-07T07:15:19Z

README.md

+If you plan to use the library in your own IoT Agent, you should read the [Developer Guide](./doc/devel/development.md).
+You can also review the [Architecture](./doc/devel/architecture.md) documentation and
+[Northbound API](./doc/devel/northbound-api.md).

-   Details of the architecture of an IoT Agent be found [here](doc/architecture.md).
-   Further Advanced topics can be found [here](doc/advanced-topics.md).
-   The following features are listed as [deprecated](doc/deprecated.md).
+The following features are listed as [deprecated](doc/deprecated.md).


Comparing old and new links... this means that old advanced-topics.md is the new nortbound-api.md?

No. advanced-topics.md is embeded into api.md, already present there. As this part of the doc is intended to address readers (both users and developers) to the most interesting files for them, I included api.md for end users, and development.md, architecture.md and northbound-api.md for developers users.

fgalan · 2023-09-07T07:18:38Z

doc/api.md

@@ -186,7 +186,7 @@ Some transformation plugins also allow the use of the following optional fields:
    be defined as expressions, using the [Expression Language definition](#expression-language-support).
 -   **entity_type**: configures the type of an alternative entity.
 -   **reverse**: add bidirectionality expressions to the attribute. See the **bidirectionality** transformation plugin
-    in the [Data Mapping Plugins section](development.md#bidirectionality-plugin-bidirectional) for details.
+    in the [Data Mapping Plugins section](.devel/development.md#bidirectionality-plugin-bidirectional) for details.


Bidirectional plugin is deprecated. This reserve bullet should be removed (along with the #bidirectionally-plugin-bidirectional section in the development.md file, if already there).

Done here: 8fe383d
And noted here: #1329 (comment)

fgalan · 2023-09-07T07:25:21Z

doc/devel/development.md

+| `attributes`                   | `attributes`                   |                                                                                                                                                   |
+| `static_attributes`            | `staticAttributes`             |                                                                                                                                                   |
+| `internal_attributes`          | `internalAttributes`           |                                                                                                                                                   |
+| `expressionLanguage`           | `expresionLanguage`            | _Removed_                                                                                                                                         |


Suggested change

| `expressionLanguage` | `expresionLanguage` | _Removed_ |

Given it its decreated functionality and acccoring to https://github.com/telefonicaid/iotagent-node-lib/blob/master/doc/deprecated.md

Documentation on deprecated features is removed from the repository documentation.

In this case, it is better to do in a subsequent PR. Noted here: #1329 (comment)
NTC

fgalan · 2023-09-07T07:25:36Z

doc/devel/development.md

+| `commands`            | `commands`           |                                                                                                                                      |
+| `internal_attributes` | `internalAttributes` | List of internal attributes with free format for specific IoT Agent configuration. I.E:LWM2M mappings from object URIs to attributes |
+| `static_attributes`   | `staticAttributes`   |                                                                                                                                      |
+| `expressionLanguage`  | `expresionLanguage`  | _Removed_                                                                                                                            |


Suggested change

| `expressionLanguage` | `expresionLanguage` | _Removed_ |

Idem

In this case, it is better to do in a subsequent PR. Noted here: #1329 (comment)
NTC

fgalan

LGTM

mapedraza added 3 commits May 19, 2023 13:19

devel file + rearrangement

4459044

Restore api.md toc

5415d19

Restore api.md toc v2

8040101

mapedraza marked this pull request as draft May 19, 2023 11:34

mapedraza added 2 commits September 6, 2023 13:50

Embed howto into development.md

61b267e

Fix development TOC

37ab4b7

mapedraza marked this pull request as ready for review September 6, 2023 11:57

mapedraza mentioned this pull request Sep 6, 2023

Documentation rework #1329

Open

25 tasks

Merge branch 'task/doc-rework' into task/doc-rework-development

c80b75d

fgalan reviewed Sep 6, 2023

View reviewed changes

doc/devel/development.md Show resolved Hide resolved

fgalan reviewed Sep 6, 2023

View reviewed changes

doc/devel/development.md Show resolved Hide resolved

fgalan reviewed Sep 6, 2023

View reviewed changes

doc/devel/development.md Show resolved Hide resolved

mapedraza added 3 commits September 6, 2023 14:47

Fix links

1431fc5

Add outdated warnings

e46c18c

rework datamodel tables

aef1589

fgalan reviewed Sep 7, 2023

View reviewed changes

This comment was marked as duplicate.

Sign in to view

mapedraza added 2 commits September 7, 2023 10:15

remove bidirectionality from api.md

8fe383d

addded db warning

9390511

fgalan approved these changes Sep 7, 2023

View reviewed changes

fgalan merged commit 2559ca7 into task/doc-rework Sep 7, 2023

fgalan deleted the task/doc-rework-development branch September 7, 2023 09:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Doc Rework] Devel files #1371

[Doc Rework] Devel files #1371

mapedraza commented May 19, 2023 •

edited

Loading

fgalan commented Sep 6, 2023

fgalan Sep 6, 2023 •

edited

Loading

mapedraza Sep 6, 2023

fgalan Sep 6, 2023

mapedraza Sep 6, 2023

fgalan Sep 6, 2023

mapedraza Sep 6, 2023

fgalan Sep 6, 2023

mapedraza Sep 6, 2023

mapedraza Sep 7, 2023

fgalan Sep 6, 2023

mapedraza Sep 6, 2023

fgalan Sep 7, 2023

mapedraza Sep 7, 2023

fgalan Sep 7, 2023

fgalan Sep 7, 2023

fgalan Sep 7, 2023

mapedraza Sep 7, 2023

fgalan Sep 7, 2023

fgalan Sep 7, 2023

mapedraza Sep 7, 2023

fgalan Sep 7, 2023

mapedraza Sep 7, 2023

fgalan Sep 7, 2023

mapedraza Sep 7, 2023

This comment was marked as duplicate.

fgalan left a comment


		- _newIoTAInfo_: Object containing all the IoTA Information.

		## DB Models (from API document)

[Doc Rework] Devel files #1371

[Doc Rework] Devel files #1371

Conversation

mapedraza commented May 19, 2023 • edited Loading

fgalan commented Sep 6, 2023

fgalan Sep 6, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

doc/development.md

doc/usermanual.md

doc/development.md

doc/howto.md

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as duplicate.

fgalan left a comment

Choose a reason for hiding this comment

mapedraza commented May 19, 2023 •

edited

Loading

fgalan Sep 6, 2023 •

edited

Loading