search

behave / behave

BDD, Python style.
https://behave.readthedocs.io/en/latest/
Other
3.19k stars 645 forks source link

Self-hosted living documentation #1018

Closed stefanitsky closed 2 years ago

stefanitsky commented 2 years ago

Hi! Can anyone please suggest a tool for a living documentation, that:

Cloud-hosted solutions, that I found, for example:

stefanitsky commented 2 years ago

I will be glad to hear any ideas and thoughts!

stefanitsky commented 2 years ago

Ok, as I understand, I can use https://www.picklesdoc.com/ on unix based machine with https://www.mono-project.com/, but it's not comfortable solution...

stefanitsky commented 2 years ago

So, it's time to write my own living docs generator in python? 😂

stefanitsky commented 2 years ago

Ok, I settled on a solution with https://www.picklesdoc.com/ with mono. Inspired by this topic (includes docker image example).

jenisys commented 2 years ago

Besides the other ones that you mentioned above: You seem to overlook the obvious choice, especially if your documentation should combine the normally written documents with the feature files (as living documentation).

Therefore, you just need to provide a simple script for the first step.

EXAMPLE: Noteworthy in Version 1.2.6 — Async Dispatch

.. literalinclude:: ../examples/async_step/features/async_dispatch.feature
    :language: gherkin
    :prepend: # -- FILE: features/async_dispatch.feature
blaisep commented 2 years ago

Jens,

This is a really cool Sphinx trick!

-Blaise

On Tue, Apr 26, 2022 at 4:16 PM jenisys @.***> wrote:

Besides the other ones that you mentioned above: You seem to overlook the obvious choice, especially if your documentation should combine the normally written documents with the feature files (as living documentation).

  • Use a simple text template engine, like Jinja2, that generates ReStructuredText or Markdown files that refer to the existing feature files (via include statements)
  • Use a documentation generator, like Sphinx or …, that converts the ReStructuredText/Markdown files into HTML based documentation (or other formats)
  • In addition, you may also want to document the steps from step libraries in another chapter (generated by the behave sphinx.steps formatter)

Therefore, you just need to provide a simple script for the first step.

EXAMPLE: Noteworthy in Version 1.2.6 — Async Dispatch https://github.com/behave/behave/blob/main/docs/new_and_noteworthy_v1.2.6.rst#async-dispatch-and-async-collect

.. literalinclude:: ../examples/async_step/features/async_dispatch.feature

:language: gherkin

:prepend: # -- FILE: features/async_dispatch.feature

— Reply to this email directly, view it on GitHub https://github.com/behave/behave/issues/1018#issuecomment-1110208289, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAB6D6HTMTZ3HBFMAJVARM3VHBFIVANCNFSM5UE4R7HQ . You are receiving this because you are subscribed to this thread.Message ID: @.***>

-- LinkedIn https://www.linkedin.com/in/blaisepabon/ | Quora https://www.quora.com/profile/Blaise-Pabon | Github https://github.com/blaisep “If you want to go fast, go alone. If you want to go far, go together.” --African proverb