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

Change documentation to use RST directly #1643

Merged
merged 6 commits into from Nov 4, 2019

Conversation

@rbberger
Copy link
Member

rbberger commented Aug 22, 2019

Summary

Adding the auto-generated RST files to version control is the first step of moving the documentation to RST-only. make rst will regenerate the RST files based on the txt files. Once the migration is complete the conversion tools will be retired.

Related Issues

#1533

Author(s)

@rbberger (Temple University)

Licensing

By submitting this pull request, I agree, that my contribution will be included in LAMMPS and redistributed under either the GNU General Public License version 2 (GPL v2) or the GNU Lesser General Public License version 2.1 (LGPL v2.1).

Backward Compatibility

HTML docs are now built directly from the RST files that are part of this repo. There is no temporary directory in /tmp anymore.

Implementation Notes

The documentation build and its files are directly written into the doc folder. Files that are not supposed to be checked in are in .gitignore

Post Submission Checklist

Please check the fields below as they are completed after the pull request has been submitted. Delete lines that don't apply

  • The feature or features in this pull request is complete
  • Licensing information is complete
  • Corresponding author information is complete
  • The source code follows the LAMMPS formatting guidelines
  • Suitable new documentation files and/or updates to the existing docs are included
  • The added/updated documentation is integrated and tested with the documentation build system
  • The feature has been verified to work with the conventional build system
  • The feature has been verified to work with the CMake based build system
  • A package specific README file has been included or updated
  • One or more example input decks are included

Further Information, Files, and Links

Put any additional information here, attach relevant text or image files, and URLs to external sites (e.g. DOIs or webpages)

rbberger added 2 commits Aug 22, 2019
This is the first step for moving the documentation format from *.txt to the
*.rst format.

In the last years we've been automatically converting txt files from Steve's
markup into RST to generate the documentation pages via Sphinx. The decision
has now been made to fully migrate to RST and avoid the conversion in the
future.

This will enable us to fully use RST and Sphinx to improve the documentation.

For the intermediate period, while there are still pending PRs with
documentation changes, we will keep both source files and update the RST files
accordingly.
@eagunn

This comment has been minimized.

Copy link
Collaborator

eagunn commented Aug 23, 2019

@rbberger I'm back online and expect to be able to contribute a few to several hours a week to lammps this semester. Please let me know how I can help with this PR and, in particular, if you think you'll want to use anything directly from #1533 or or I should just close it.

@rbberger

This comment has been minimized.

Copy link
Member Author

rbberger commented Aug 27, 2019

@eagunn after this one is merged, I want to create PRs that have your toolchain changes from #1533. E.g. adding the Docker container, the RST anchor check and any additional changes that were needed to support epub and such. Keep your PR open for now, it's a draft anyway.

@akohlmey akohlmey self-assigned this Oct 31, 2019
@akohlmey

This comment has been minimized.

Copy link
Member

akohlmey commented Oct 31, 2019

@rbberger as discussed in person, I would like to merge this PR next, so that we finally begin the transition to writing documentation directly in RST. We should leave the conversion toolchain around until after the next stable release. but we should already remove the support for the legacy documentation via txt2html and htmldoc. Could you please update this PR to the state of the current master?

@rbberger

This comment has been minimized.

Copy link
Member Author

rbberger commented Nov 3, 2019

@akohlmey done.

@eagunn

This comment has been minimized.

Copy link
Collaborator

eagunn commented Nov 4, 2019

@rbberger Glad to see you are making progress on this big, long-term change. I'm finding that in-semester teaching duties are giving me no time to help. But I will have a month, from mid-December to mid-January without day-to-day content and grading duties. If there's anything I can do to help during that interim period, I'd be happy to give it a go. Would still like to find a role to contribute over the long run.

@akohlmey akohlmey self-requested a review Nov 4, 2019
Copy link
Member

akohlmey left a comment

Finally pulling the trigger on this one...
Everybody watch out for bits and pieces flying around. ;-)

@akohlmey akohlmey merged commit e204393 into lammps:master Nov 4, 2019
8 checks passed
8 checks passed
lammps/pull-requests/build-docs-pr head run ended
Details
lammps/pull-requests/cmake/cmake-kokkos-cuda-pr head run ended
Details
lammps/pull-requests/cmake/cmake-kokkos-omp-pr head run ended
Details
lammps/pull-requests/cmake/cmake-serial-pr head run ended
Details
lammps/pull-requests/kokkos-omp-pr head run ended
Details
lammps/pull-requests/openmpi-pr head run ended
Details
lammps/pull-requests/serial-pr head run ended
Details
lammps/pull-requests/shlib-pr head run ended
Details
@rbberger rbberger mentioned this pull request Nov 5, 2019
4 of 10 tasks complete
@rbberger rbberger mentioned this pull request Nov 14, 2019
6 of 6 tasks complete
@rbberger rbberger deleted the rbberger:docs_to_rst_migration branch Nov 14, 2019
@rbberger rbberger mentioned this pull request Nov 17, 2019
6 of 6 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.