Stage 055 documentation #188
Conversation
This means that Sphinx will attempt to process the stage's script, nothing more. The script's contents are yet to be updated to properly describe the stage.
This includes the explanation for 'initial JSON' in the stage description.
There was a problem hiding this comment.
Commit 1541939 ("Improved documents_links() function."):
I would rather describe this change as "Renamed document_links() function." or "Unified functions name."
Improvement means that something has became better -- and if it is said that the function was improved, I would expect some changes in its behaviour (works faster, more failsafe, etc).
Other comments are in the code comments.
- Renamed the function to document_links() to be in line with document_cds() and document_glance(). - Also clarified description a bit.
- Created a chapter called "Stages". - Changed Stage 055 to be a section of this chapter instead of a separate chapter.
Evildoor
force-pushed
the
stage-055-docs-v2
branch
from
1541939 to
9f5d175
Compare
|
Reworded 1541939 and made the suggested change regarding the "Stages" chapter. Other comments seem to be valid, will do later. |
The description now states which variables are defined and how their values are chosen.
Added missing information about return value and its type.
process()' role, input and output are different from those of a typical function, so they were clarified.
|
@mgolosova - please, take a look. All of the issues were fixed, commented or depend on other commented issues. |
While the main goal of fix_string() is to adjust strings, it can also process arbitrary objects by returning them as-is. Document this possibility.
Fetch changes from master. Resolve conflicts in code and remake the docs. Conflicts: Docs/build/html/_modules/index.html Docs/build/html/_modules/pyDKB/dataflow/communication/messages.html Docs/build/html/_modules/pyDKB/dataflow/stage/AbstractProcessorStage.html Docs/build/html/_modules/pyDKB/dataflow/stage/processors.html Docs/build/html/genindex.html Docs/build/html/objects.inv Docs/build/html/pyDKB/pyDKB.dataflow.messages.html Docs/build/html/pyDKB/pyDKB.dataflow.stage.AbstractProcessorStage.html Docs/build/html/pyDKB/pyDKB.dataflow.stage.processors.html Docs/build/html/pyDKB/pyDKB.dataflow.types.html Docs/build/html/searchindex.js Docs/build/pdf/DKB.pdf Utils/Dataflow/016_task2es/input Utils/Dataflow/055_documents2TTL/documents2ttl.py
Some functions can return None instead of desired values if these values were not found in the supplied data.
Evildoor
force-pushed
the
stage-055-docs-v2
branch
from
be3827c to
ea2fd89
Compare
- Move the definition "initial JSON" higher - the earlier it is introduced, the better. Also, this would prevent ambiguity since the "JSON file should" line can be interpreted as "any JSON file should". - Change "JSON file" to "JSON document" - there is no restriction that the JSON must be a file.
| :param stage: stage instance | ||
| :type stage: pyDKB.dataflow.stage.ProcessorStage | ||
| :param msg: input message with initial JSON | ||
| :type msg: pyDKB.dataflow.Message |
There was a problem hiding this comment.
| :type msg: pyDKB.dataflow.Message | |
| :type msg: pyDKB.dataflow.communication.messages.JSONMessage |
There was a problem hiding this comment.
Just a comment: could also be decorated with :py:class:, but I suggest us to leave it for another PR.
| stage.output(pyDKB.dataflow.Message( | ||
| pyDKB.dataflow.messageType.TTL)(item)) |
There was a problem hiding this comment.
Just a comment: and here I noticed that Message() call in this function is broken (fixed in #311).
|
Had to make suggested single-line commits by hand because each one has to update the docs as well. |
|
@Evildoor, thank you, request is accepted. |
Added basic documentation for stage 055 and changed the name of one function(this is made here per agreement on meeting).