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

Refactor building docs #858

Merged
merged 5 commits into from
Jun 29, 2020
Merged

Refactor building docs #858

merged 5 commits into from
Jun 29, 2020

Conversation

webknjaz
Copy link
Member

@webknjaz webknjaz commented Jun 23, 2020

This change is only a first (small) step towards making the docs setup better.

  • It introduces an explicitly defined RTD config.
  • It gets rid of Makefiles moving everything under one roof with other processes (tox).

Everything else is kept out intentionally: small changes are easier to reason about and accepting them fast allows us to minimize conflicts with related changes.

@webknjaz webknjaz self-assigned this Jun 23, 2020
@webknjaz webknjaz force-pushed the docs/sphinx-setup-refactoring branch from bea3777 to ad30e9f Compare June 23, 2020 20:06
@ssbarnea ssbarnea self-requested a review June 24, 2020 06:49
Copy link
Member

@ssbarnea ssbarnea left a comment

Choose a reason for hiding this comment

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

I am inclined to support an approach where we first remove the in-repo-theme and replace it with sphinx-ansible-theme via #856

We can refactor the docs layout after we do this. My experiement worked really fine and proved that RTD can build our docs nicely. Take a look at mentioned PR.

Current sphinx-ansible-theme does not add any customizations yet, but this is what I am going to do now, mainly taking current Ansible theme into it.

@webknjaz
Copy link
Member Author

@ssbarnea I agree that we need to get the theme out of the repo but, as I see it, it's easier to go it step-by-step with small incremental changes like this one.

@webknjaz webknjaz marked this pull request as ready for review June 25, 2020 20:24
@ssbarnea
Copy link
Member

@webknjaz I am ok with the incremental approach but there is one critical issue: the RTD build is broken and this build also breaks the zuul publishing due to changed path, practically making impossible to review the outcome of the change.

If RTD would render fine, I would merge it right now.

@webknjaz
Copy link
Member Author

I think you could change Zuul config to improve this. Right now I don't want to overwhelm it with too many changes.

@webknjaz webknjaz mentioned this pull request Jun 26, 2020
@webknjaz webknjaz force-pushed the docs/sphinx-setup-refactoring branch from 1d1e799 to a864ac9 Compare June 26, 2020 12:50
webknjaz added a commit to webknjaz/ansible-zuul-jobs that referenced this pull request Jun 26, 2020
@webknjaz
Copy link
Member Author

@ssbarnea here I've adjusted the var to point to the changed location ansible/ansible-zuul-jobs#576

@webknjaz webknjaz force-pushed the docs/sphinx-setup-refactoring branch 3 times, most recently from a93f7a0 to eec471a Compare June 28, 2020 22:44
@webknjaz webknjaz force-pushed the docs/sphinx-setup-refactoring branch from eec471a to 1ccf634 Compare June 28, 2020 22:51
@webknjaz webknjaz force-pushed the docs/sphinx-setup-refactoring branch from ce29199 to a06b0fb Compare June 28, 2020 23:33
@ssbarnea ssbarnea merged commit e659f71 into master Jun 29, 2020
@ssbarnea ssbarnea deleted the docs/sphinx-setup-refactoring branch June 29, 2020 07:50
@webknjaz webknjaz mentioned this pull request Jul 1, 2020
@ssbarnea ssbarnea added skip-changelog Can be missed from the changelog. and removed priority/high labels Aug 17, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
skip-changelog Can be missed from the changelog.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants