Project

General

Profile

Actions

User story #1621

closed

Generate documentation for std lib Techniques from their source code

Added by Fabrice FLORE-THÉBAULT over 13 years ago. Updated about 4 years ago.

Status:
Resolved
Priority:
4
Assignee:
-
Category:
Documentation
UX impact:
Suggestion strength:
User visibility:
Effort required:
Name check:
Fix check:
Regression:

Description

EDIT: This conversation has been translated

[14:30] <themroc> Question: every PT comes with a description, should-we copypaste it in the doc or try to generate this part from the PT description itself?
[14:31] <themroc> Because we already have a different description in the beta doc and the GUI
[14:31] <themroc> (maintenance issues ahead)
[14:34] <fanf> themroc: actually, the PT documentation should be an annex generated from the actual PTs, for every Rudder version
[14:35] <fanf> or yes, it will never be correct


Related issues 1 (0 open1 closed)

Related to Rudder - User story #2328: Autodocument configuration filesRejectedActions
Actions #1

Updated by Fabrice FLORE-THÉBAULT over 13 years ago

create a script which is able to do following :

  1. list all available PT
  2. extract informations from each PT :
    1. PT_name;
    2. PT_description;
    3. PT_catagory;
  3. create a well formatted asciidoc document available_pt.txt using these informations, following this template :
    ===== Category 1
    
    PT1_Name:: PT1_Desccription
    
    PT2_Name:: PT2_Desccription
    
    ===== Category 2
    
    PT1_Name:: PT1_Desccription
    
    PT2_Name:: PT2_Desccription
    
    

then replace in the documentation the actual content by a call to this script + call to include the generated file

Actions #2

Updated by Fabrice FLORE-THÉBAULT over 13 years ago

  • Assignee changed from Fabrice FLORE-THÉBAULT to François ARMAND
Actions #3

Updated by Fabrice FLORE-THÉBAULT over 13 years ago

to have the policy templates source, we should check-out the source ; where to store this files ? either : temp directory, which is deleted by make clean, or another directory that will be keeped after first build, and only updated afterwards (what is the best?)

the action should be added to already existing script generate-map.sh and the file should be produced into temp/available_pt.txt

then uncomment the include line, in 2_usage/2_available_policy_templates.txt and cleanup the file

Actions #4

Updated by Fabrice FLORE-THÉBAULT about 13 years ago

  • Status changed from New to 2
  • Priority changed from 5 (lowest) to 4
Actions #5

Updated by Fabrice FLORE-THÉBAULT about 13 years ago

  • Target version changed from 10 to 19
Actions #6

Updated by Fabrice FLORE-THÉBAULT about 13 years ago

  • Assignee changed from François ARMAND to Matthieu CERDA
Actions #7

Updated by Matthieu CERDA about 13 years ago

I'm stealing the bug from FAR.

Actions #8

Updated by Jonathan CLARKE about 13 years ago

  • Target version changed from 19 to 21
Actions #9

Updated by Fabrice FLORE-THÉBAULT about 13 years ago

  • Target version changed from 21 to 10
Actions #10

Updated by François ARMAND about 13 years ago

  • Target version changed from 10 to 2.3.1
Actions #11

Updated by Jonathan CLARKE about 13 years ago

  • Target version changed from 2.3.1 to 2.3.2
Actions #12

Updated by Jonathan CLARKE about 13 years ago

  • Target version changed from 2.3.2 to 2.3.3
Actions #13

Updated by Jonathan CLARKE about 13 years ago

  • Target version changed from 2.3.3 to 2.3.4
Actions #14

Updated by Matthieu CERDA about 13 years ago

  • Status changed from 2 to Discussion
  • Assignee deleted (Matthieu CERDA)

The tool required to do that is on the rudder doc repo in tools/pt2doc. I can just not find a way to execute the script in the right order to generate the asciidoc compatible list.

Actions #16

Updated by Jonathan CLARKE almost 13 years ago

  • Target version changed from 2.3.4 to 2.3.5
Actions #17

Updated by Jonathan CLARKE almost 13 years ago

  • Target version changed from 2.3.5 to 2.3.6
Actions #18

Updated by Jonathan CLARKE almost 13 years ago

  • Target version changed from 2.3.6 to 2.3.7
Actions #19

Updated by Jonathan CLARKE over 12 years ago

  • Target version changed from 2.3.7 to 2.3.8
Actions #20

Updated by Jonathan CLARKE over 12 years ago

  • Target version changed from 2.3.8 to Ideas (not version specific)
Actions #21

Updated by Benoît PECCATTE over 9 years ago

  • Project changed from 30 to Rudder
  • Category set to Documentation
Actions #22

Updated by Matthieu CERDA over 9 years ago

  • Subject changed from generate list of available PT from source code of PT. to Generate a list of available PTs from their source code
  • Description updated (diff)
  • Status changed from Discussion to Rejected

I feel that ncf and a much better presentation of Techniques in the current UI makes this issue obsolete. Feel free to reopen if necessary.

Actions #23

Updated by Vincent MEMBRÉ over 9 years ago

  • Status changed from Rejected to Discussion
  • Assignee set to François ARMAND

I am not ok with you Matthieu, The goal of this is to always have an up to date documentation of all available techniques, which we do not have.

I reopen this issue, which needs to be discussed, What do you think François ?

Actions #24

Updated by Jonathan CLARKE over 9 years ago

  • Subject changed from Generate a list of available PTs from their source code to Generate a list of available Techniques from their source code

I agree with you Vincent, as long as we still provide Techniques, we should have an up to date doc (like a repository viewer) of all available Techniques. If we stop providing such Techniques, then this could be rejected.

Actions #25

Updated by François ARMAND almost 7 years ago

  • Subject changed from Generate a list of available Techniques from their source code to Generate documentation for std lib Techniques from their source code
  • Status changed from Discussion to New
  • Assignee deleted (François ARMAND)

Agreed.

Actions #26

Updated by François ARMAND about 4 years ago

  • Status changed from New to Resolved

This will never be done since we want away from technique like that. ncf method have embeded technical documentation, and user-made technique can have functionnal documentation.

Actions

Also available in: Atom PDF