Giters

Chris1221 / yamldoc

Dependency-free YAML documentation engine.

Home Page:http://chrisbcole.me/yamldoc/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Choose certain lines and have more nests

yahya280101 opened this issue · comments

commented

Hello Chris,

I am using your package, I was trying to document a YML file and I wanted to choose some lines and leave others like for example `#' This is a flat entry.
flat: "yes"

#' But this is a two level thing.
two:
#' These can have documentation too.
entry: "hi"
#' this is the colour
color: "red"
#' this is the phone I don't want to include in my sphinx documentation
phone: "0123456789"`

So I don't want to include phone in my documentation however I want the others, is there a way to do it,

I am also using the complex scheme for nested lines, but is it possible that we have a value and inside it a value that has members inside it, example:
`#' This is a flat entry.
flat: "yes"

#' But this is a three level thing.
two:
#' These can have documentation too.
entry:
#' this is the colour
color: "red"
#' this is the phone I don't want to include in my sphinx documentation
phone: "0123456789"`

So two would be at the top and it has entry that has a member which is color, if you'd have answers two those questions Id really appreciate it.

commented

Hi @yahya280101, thanks for using the tool!

As for your first point, selectively disabling lines is not a feature that I have enabled right now. It would be very easy to implement though, if you're not in a rush I could probably get to it in a few days. You could also use grep to remove the entry from the file after you've generated it if you're using this in sphinx.

The triple nested membership issue is a little trickier. I don't know what that would look like, right now the object (two in your example) is the header in the generated markdown and the elements are listed in a table. What would it look like if you had a triple nested variable? This is probably a bit more work and might not be something I'm interested in implementing at the moment. If you want to give it a go with the code that's here though, please go ahead and let me know how it goes. Happy to help out if there's anything that's confusing.

commented

For example, with your first document (you can use three backticks to format by the way):

test.yaml:

#' But this is a two level thing.
two:
  #' These can have documentation too.
  entry: "hi"
  #' this is the colour
  color: "red"
  #' this is the phone I don't want to include in my sphinx documentation
  phone: "0123456789"`
yamldoc test.yaml | grep -v phone

gives

# Configuration Parameters Reference

Any information about this page goes here.

## `two`

But this is a two level thing.

### Member variables:

| Key | Value | Information |
| :-: | :-: | :-- |
| `entry` | `"hi"` | These can have documentation too. |
| `color` | `"red"` | this is the colour |

---
Generated by [yamldoc](https://github.com/chris1221/yaml.doc) v0.1.6 on 2023-06-14

grep -v means "find all the lines that do not match the pattern" and the pattern is "phone".

commented

I'm updating the code to fix some bugs right now so I would recommend that you clone the version from the master branch and use that instead of the one on Pypi. I'll be updating that soon but I haven't gotten around to it yet.

git clone https://github.com/Chris1221/yamldoc.git 
pip install -e ./yamldoc
commented

Thank you so much for your reply,

I am actually not in rush, I would appreciate much, because my yaml file has many entries and it would require me to go through entry entry, and also some parts are commented out and the commented out parts still appear in the documentation (which are lines I dont won't to document but still want to leave as they might be used soon), So what I was thinking about is it possible to do something that doesn't affect the code but still takes the lines out like for example starting with #? and ending with #$ (making it up) would suspend a certain block or line of code (for documentation) but still the code it self is functional.
example:
` ```
#' This is a flat entry.
flat: "yes"

#' But this is a two level thing.
two:
#' These can have documentation too.
entry: "hi"
#' this is the colour
color: "red"
#?
phone: "0123456789" `
#$

#?
# feature: fast this is a commented out feature
#$`

so this would work for lines already in the code and lines that are commented out and both types you dont need in the documentation
commented

yamldoc test.yaml | grep -v phone also how does this work with -c basic.schema

commented

For sure, if you aren't in a rush I can add this feature in a few days. I like your idea though I might change the syntax a little. I'll ping you on this issue when I have a working version, I have a good idea how to attack this already.

yamldoc test.yaml | grep -v phone also how does this work with -c basic.schema

The | here is a bash pipe, so it takes the output of the first command and gives it as input to the second command. Here's an explanation if you're interested. To use this with a schema, you can give it as an option like you would normally and then pipe the output to grep to remove the lines you want. (The syntax for including the schema is the -s switch by the way, the -c switch is to give the prefix character).

yamldoc test.yaml -s basic.schema | grep -v phone

You can try this with the test data to try it out:

yamldoc test/yaml/basic.yaml -s test/schema/basic.schema | grep -v Any
commented

Hey @yahya280101, check out PR #13 for an implementation of this. I'm going to write a little more documentation before merging it but you can give it a try by using that branch.

git clone https://github.com/Chris1221/yamldoc.git 
git checkout feat/exclusion
pip install -e ./yamldoc

I've given an example of how to specify exclusion characters and also how to override exclusion characters with --override-exclude. Let me know if you have questions or suggestions!

commented

Hello Chris,
sorry for not replying earlier, I am going to try it now thanks a lot, I will let you know soon. Thanks again.

commented

Hello Chris,

I think its working very nice and smooth, thanks a lot, I also have some questions if you don't mind:

  1. How to remove the type column when using a scheme as I don't want to show It in the documentation?

  2. How to deal with such a thing:

.......
colors:
-red
-blue


when I try to document such a thing with the new feature it gives an error : AttributeError: 'ListElement' object has no attribute 'exclude'

3. Any ideas of the nested variables?

at the end I would to like to thank you much for the great effort, you are helping a lot and I am looking forward to hearing from you soon.
commented

So the problem is not in the list its when there is a nested list:

Place:
    colors:

             -red
             -blue
commented

Great catch! I've fixed this in the PR and merged it. If this doesn't fix your issue please feel free to re-open this ticket.

Place:
  colors:
    - red
    - blue

now reports:

Key Value Information
colors ['red', 'blue']

as expected :)

I've moved the work on arbitrary nested levels to #14 to separate things out. I have an idea on how to implement this but it may take a bit longer. Hopefully this is enough to get you going for the moment.

commented

I will check and let you know thanks a lot, and this is enough yes I will work around with it 😀