Add environment variables

[flagarde]

Hi, First thanks a lot for this project. It simplify a lot the documenting process .

Is your feature request related to a problem? Please describe.
It seems not possible to document environment variables

Describe the solution you'd like
Would it be possible to add :env ?

Describe alternatives you've considered
For now i'm using this kind of tricks :

#  Environment variables:
#
#  CLICOLOR_FORCE to force ANSI escape code colors. https://bixense.com/clicolors/
#
#  CLICOLOR to disable ANSI escape code colors. https://bixense.com/clicolors/
#
#  CMMM_DEFAULT_COLOR to set default color (`[0;35m`).
#
#  CMMM_FATAL_ERROR_COLOR to set fatal error color (`[1;31m`).
#
#  CMMM_ERROR_COLOR to set error color (`[0;31m`).
#
#  CMMM_WARN_COLOR to set warn color (`[0;33m`).
#
#  CMMM_INFO_COLOR to set info color (`[0;32m`).
#

Additional context
Sometimes environment variables are used inside functions or macros. Even CMake uses them to override some variables.

[ryanmrichard]

@flagarde Thanks you the feedback! It's always great to hear people are enjoying CMinx.

With regards to your issue, reST seems to have directive and role support for environment variables, but for the life of me I can't seem to find something akin to the :keyword <name>: syntax (AFAIK :envvar <name>: doesn't work, but I admittedly didn't try). @AutonomicPerfectionist any idea how one normally documents environment variables in Python (I personally avoid using environment variables in my own Python, and after 20+ minutes of searching I apparently can't seem to find any relevant tutorials).

@flagarde I assume you're looking for something more akin to the keyword syntax (:keyword <name>:), but for environment variables? If so, if CMinx is given something like:

#[[[
# :envvar CLICOLOR_FORCE: to force ANSI escape code colors. https://bixense.com/clicolors/#144 
#]]

and generated something like:

**Environment Variables**
   
   :param CLICOLOR_FORCE: to force ANSI escape code colors. https://bixense.com/clicolors/#144 

would that suffice?

[flagarde]

@ryanmrichard Thx for your fast response. I try to avoid environment variables too but it seems I have found a situation in which I can't escape from using them. CMake uses them quite a lot too...

Yes, I'm looking for something similar to :keywors : and maybe :type : too. I think it would suffice for most of the cases.

[AutonomicPerfectionist]

@ryanmrichard to answer your question, no I don't know how one would document environment variables in Python. I haven't been able to find much, either. We could do your solution with the custom :envvar <NAME>: field, but I would need to figure out how to parse that correctly. Right now, we aren't really doing anything with the raw documentation, just cleaning the leading # characters. The biggest issue I see with doing a simple regex search for that custom field is that if it's not intended to be parsed, like inside of a code block in the documentation, it would still be altered anyway. Not really sure if that's a big issue though

[ryanmrichard]

@AutonomicPerfectionist how do we avoid the code block problem when looking for kwargs? Or don't we?

[AutonomicPerfectionist]

We don't currently, it's just a simple string search with the search pattern set in the config. If we were to implement parsing for the envvar that would be adjusted to also use the parsing system

[ryanmrichard]

@AutonomicPerfectionist that sounds good. In theory :envvar <name>: shouldn't show up in a code block, since it's not a valid reST field, so I suspect we'll be fine for 99.9% of usecases.