Publishing documentation to readthedocs.com

Hi!

I'm working on publishing documentation to readthedocs.org. However, our documentation is spread over several repositories and readthedocs can only fetch from single one.
I came up with two solutions:

1. Moving all documentation to the new repository openlmis-documentation

2. Keeping only general documents in openlmis-documentation and having a python script executed by readthedocs that collects documents from other repositories to build whole documentation.
I have made an example in my repository:
https://github.com/garaminowicz/documentation-test

Please let me know what do you think and which solution do you prefer.

Regards,
Grzegorz

Moving all documentation to one repo isn’t viable — the docs must live
with their respective sources, so I think we will need to have a process
that knows about all of the sources and fetches the docs.

In our original solution, we anticipated having a ‘distribution’ repo with
the recipe to assemble the entire reference app. Not sure if this has been
superseded by Docker + Consul, but having a separate doc build task
defined here would make sense to me. If someone forked it to create a
specific distribution with only a few services, for example, they would
just get the docs for those services …

Regardless, I think the solution probably lies in the build process.

On 8/25/16, 9:32 AM, "openlmis-dev@googlegroups.com on behalf of Grzegorz
Araminowicz" <openlmis-dev@googlegroups.com on behalf of
garaminowicz@soldevelo.com> wrote:

···

Hi!

I'm working on publishing documentation to readthedocs.org. However, our
documentation is spread over several repositories and readthedocs can
only fetch from single one.
I came up with two solutions:

1. Moving all documentation to the new repository openlmis-documentation

2. Keeping only general documents in openlmis-documentation and having a
python script executed by readthedocs that collects documents from other
repositories to build whole documentation.
I have made an example in my repository:
https://github.com/garaminowicz/documentation-test

Please let me know what do you think and which solution do you prefer.

Regards,
Grzegorz

--
You received this message because you are subscribed to the Google Groups
"OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to openlmis-dev+unsubscribe@googlegroups.com.
To post to this group, send email to openlmis-dev@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/openlmis-dev/472b7552-b376-daac-be0c-540
055b0b18b%40soldevelo.com.
For more options, visit https://groups.google.com/d/optout.

I finished working on that ticket. Now in one place there are only general documents and configuration files. Other documents are collected from other repositories by a python script. They are pulled and built by readthedocs.org. This action is defined as Jenkins job that runs nightly.

Where do you prefer to keep these general files? In a new dedicated repository openlmis-documentation or maybe somewhere else (openlmis-blue?).

···

On 25.08.2016, 23:28, Jake Watson wrote:

Moving all documentation to one repo isn’t viable — the docs must live
with their respective sources, so I think we will need to have a process
that knows about all of the sources and fetches the docs.

In our original solution, we anticipated having a ‘distribution’ repo with
the recipe to assemble the entire reference app. Not sure if this has been
superseded by Docker + Consul, but having a separate doc build task
defined here would make sense to me. If someone forked it to create a
specific distribution with only a few services, for example, they would
just get the docs for those services …

Regardless, I think the solution probably lies in the build process.

On 8/25/16, 9:32 AM, "openlmis-dev@googlegroups.com on behalf of Grzegorz
Araminowicz" <openlmis-dev@googlegroups.com on behalf of
garaminowicz@soldevelo.com> wrote:

Hi!

I'm working on publishing documentation to readthedocs.org. However, our
documentation is spread over several repositories and readthedocs can
only fetch from single one.
I came up with two solutions:

1. Moving all documentation to the new repository openlmis-documentation

2. Keeping only general documents in openlmis-documentation and having a
python script executed by readthedocs that collects documents from other
repositories to build whole documentation.
I have made an example in my repository:
https://github.com/garaminowicz/documentation-test

Please let me know what do you think and which solution do you prefer.

Regards,
Grzegorz

--
You received this message because you are subscribed to the Google Groups
"OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to openlmis-dev+unsubscribe@googlegroups.com.
To post to this group, send email to openlmis-dev@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/openlmis-dev/472b7552-b376-daac-be0c-540
055b0b18b%40soldevelo.com.
For more options, visit https://groups.google.com/d/optout.

Offhand (and having ignored the finer details) I would think that we are assembling docs for one particular distribution of OpenLMIS, and we should put the docs in that distro’s repo.

(So, I think that means it goes in blue.)

-Darius

···

On Mon, Aug 29, 2016 at 2:59 AM, Grzegorz Araminowicz garaminowicz@soldevelo.com wrote:

I finished working on that ticket. Now in one place there are only general documents and configuration files. Other documents are collected from other repositories by a python script. They are pulled and built by readthedocs.org. This action is defined as Jenkins job that runs nightly.

Where do you prefer to keep these general files? In a new dedicated repository openlmis-documentation or maybe somewhere else (openlmis-blue?).

On 25.08.2016, 23:28, Jake Watson wrote:

Moving all documentation to one repo isn’t viable — the docs must live

with their respective sources, so I think we will need to have a process

that knows about all of the sources and fetches the docs.

In our original solution, we anticipated having a ‘distribution’ repo with

the recipe to assemble the entire reference app. Not sure if this has been

superseded by Docker + Consul, but having a separate doc build task

defined here would make sense to me. If someone forked it to create a

specific distribution with only a few services, for example, they would

just get the docs for those services …

Regardless, I think the solution probably lies in the build process.

On 8/25/16, 9:32 AM, "openlmis-dev@googlegroups.com on behalf of Grzegorz

Araminowicz" <openlmis-dev@googlegroups.com on behalf of

garaminowicz@soldevelo.com> wrote:

Hi!

I’m working on publishing documentation to readthedocs.org. However, our

documentation is spread over several repositories and readthedocs can

only fetch from single one.

I came up with two solutions:

  1. Moving all documentation to the new repository openlmis-documentation

  2. Keeping only general documents in openlmis-documentation and having a

python script executed by readthedocs that collects documents from other

repositories to build whole documentation.

I have made an example in my repository:

https://github.com/garaminowicz/documentation-test

Please let me know what do you think and which solution do you prefer.

Regards,

Grzegorz

You received this message because you are subscribed to the Google Groups

“OpenLMIS Dev” group.

To unsubscribe from this group and stop receiving emails from it, send an

email to openlmis-dev+unsubscribe@googlegroups.com.

To post to this group, send email to openlmis-dev@googlegroups.com.

To view this discussion on the web visit

https://groups.google.com/d/msgid/openlmis-dev/472b7552-b376-daac-be0c-540

055b0b18b%40soldevelo.com.

For more options, visit https://groups.google.com/d/optout.

You received this message because you are subscribed to the Google Groups “OpenLMIS Dev” group.

To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.

To post to this group, send email to openlmis-dev@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/bf407756-7334-1201-2f7f-3556dddef071%40soldevelo.com.

For more options, visit https://groups.google.com/d/optout.

Darius JazayeriPrincipal Architect - Global Health
Email
djazayeri@thoughtworks.com

Telephone
+1 617 383 9369

ThoughtWorks