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

Update docs about build process #4515

Merged
merged 6 commits into from Aug 21, 2018
Merged

Conversation

@stsewd
Copy link
Member

@stsewd stsewd commented Aug 13, 2018

Describe each docker image used to build the docs

ref to #4419 (comment)

Describe each docker image used to build the docs
@stsewd stsewd requested review from humitos and Aug 13, 2018
docs/builds.rst Outdated
When we build your documentation, we run `sphinx-build -b html . _build/html`, where `html` would be replaced with the correct backend. We also create man pages and pdf's automatically based on your project.
When we build your documentation, we run `sphinx-build -b html . _build/html`,
where `html` would be replaced with the correct backend.
We also create pdf's and ePub's automatically based on your project.
Copy link
Member Author

@stsewd stsewd Aug 13, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rest of the lines are the same, they were just too long. Except here, here we have had man pages, but we don't build man pages anymore.

Loading

Copy link
Member

@humitos humitos Aug 15, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't we need double for the command andhtml` here?

Loading

Copy link
Member Author

@stsewd stsewd Aug 15, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah

Loading

docs/builds.rst Outdated
* ``graphviz``
* ``pandoc``
* ``doxygen``
* ``libjpeg``
Copy link
Member Author

@stsewd stsewd Aug 13, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if all these packages are relevant, I keep the most that were in the previous description

Loading

Copy link
Member

@humitos humitos Aug 15, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, they are relevant.

Loading

Copy link
Member

@humitos humitos left a comment

Great!

I think it will be better if we sort the packages installed alphabetically.

Loading

Packages installed in the build environment
-------------------------------------------

The build server does have a select number of C libraries installed, because they are used across a wide array of python projects. We can't install every C library out there, but we try and support the major ones. We currently have the following libraries installed:
Copy link
Member

@humitos humitos Aug 15, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd keep a message similar to this one inside a .. note:: so, users are aware that we can't install everything inside the docker image.

Loading

docs/builds.rst Outdated
by default the image used is ``readthedocs/build:2.0``,
but you can change that using a :doc:`configuration file <yaml-config>`.

Each image is described below.
Copy link
Member

@humitos humitos Aug 15, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd add a .. tip:: admonition here with indicating how to verify the version of each package installed in the docker image (linking to https://packages.ubuntu.com/ for each specific version and commenting how to do it)

Loading

Copy link
Member Author

@stsewd stsewd Aug 15, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea

Loading

docs/builds.rst Outdated
* ``graphviz``
* ``pandoc``
* ``doxygen``
* ``libjpeg``
Copy link
Member

@humitos humitos Aug 15, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, they are relevant.

Loading

docs/builds.rst Outdated
The Docker image does have a select number of C libraries installed,
because they are used across a wide array of python projects.
We can't install every C library out there,
but we try and support the major ones
Copy link
Member

@humitos humitos Aug 15, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Final dot: .

Loading

Copy link
Member Author

@stsewd stsewd Aug 16, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

😭

Loading

Copy link
Member

@ericholscher ericholscher left a comment

Looks good!

Loading

@ericholscher ericholscher merged commit 6057ff9 into readthedocs:master Aug 21, 2018
1 check passed
Loading
@stsewd stsewd deleted the docs-build-process branch Aug 21, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants