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.

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

Inconsistant return value of methods in MdUtils and more #67

Open
jaredliw opened this issue Oct 27, 2021 · 2 comments
Open

Inconsistant return value of methods in MdUtils and more #67

jaredliw opened this issue Oct 27, 2021 · 2 comments

Comments

@jaredliw
Copy link
Contributor

Is your feature request related to a problem? Please describe.
Methods of MdUtils have ambiguous and inconsistant return values, here are some examples:

  1. new_table, new_reference_image, write return lines in md format;
  2. new_paragraph, new_line return whole file;
  3. new_list and new_checkbox_list returns nothing;
  4. new_inline_* do not write anything into the file, but just return strings.

Describe the solution you'd like
Apply no. 1 for all except new_inline_*.

Describe alternatives you've considered
I think no. 2 is by mistake, it contradicts the method's docstring. For no. 4, I don't have a good solution on it, maybe just write it explicitly in the documentation. It is a pain to users, I have to read the source code to debug my code...

Additional context
More suggestions:

  1. Update MdUtils.new_header's docstring, :return: is not stated;
  2. readthedocs is outdated, feed README to sphinx will do;
  3. new_inline_link could be a static method, just like new_inline_image (one is MdUtils.new_inline_image(...) and another is mdfile.new_inline_link, it's bizzare);
  4. Escape characters e.g. ], ), simple string concat won't work every time, mentioned in Escape "|" in Table.create_table #63;
  5. For place_text_using_marker, do you mean replace_text_using_marker? I don't know about the marker, my editor does not support that, but would it be overkilling to just use str.replace?
  6. Annoying wrap_width, I suggest making its default value to 0. It is not commonly used, I have to set it whenever I want to call new_line etc. I was ??? when I saw those \n appeared out of thin air, again, debugging it spent me some time;
  7. rows parameter of new_table is not that necessary, append blanks at the end of text list will do.

Enhancements:

  1. For new_table, would it be better if we supports dict type text? Maybe we should discuss this.
  2. It would be better if these params are in lists:
    • text_align of new_table: Customize each column;
    • marked_with of new_list: The nested list(s) must not follow the marker of the root list, what I mean is, an ordered list can have an unordered list in it, just like what I am using right now.
    • checked of new_checked_list: In most of the time, we don't check/uncheck the whole list at a time, a list of bools would be way better, or else I have to write the list manually in md (although I am using a lib that is doing markdown lol).

Thanks.

@didix21
Copy link
Owner

didix21 commented Oct 28, 2021

Totally agree, this code was from my early python days and I didn't have much time to check it. Anyways, we can see that there is a lot of things that can be improved. So my proposal is splitting this issue in different ones and create a project on github in order to track the state of each one.

@jaredliw
Copy link
Contributor Author

Totally agree, this code was from my early python days and I didn't have much time to check it. Anyways, we can see that there is a lot of things that can be improved. So my proposal is splitting this issue in different ones and create a project on github in order to track the state of each one.

I would be appreciate if you can do me the flavour. I am quite busy these days. I will catch you up (and maybe offer some help in dev) after I have done my stuff.

Thank ya!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants